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Abstract of Project 


The recent interest in Network Computers (NC) has kindled somewhat of 
a rebirth in as a platform for an Intel-based NC. With the bloated 
Workplace Shell and other Graphical User Interface (GUI) components 
removed, the OS/2 kernel makes a good foundation for a Java-based 
workstation. It requires the installation of a Java Virtual Machine (JVM) 
and the required operating system support for the Java Application 
Programming Interface (API). Once enabled, the system will allow for the 
execution of Java applets and Java applications using the underlying OS/2 
kernel for memory management, scheduling, dispatching, and device 


support. 


In order to take advantage of the new crop of device architectures now 
emerging, such as Universal Serial Bus (USB), Firewire, and others, the 
OS/2 device driver interface must be redesigned to support both the older 
16-bit device drivers and a new crop of 32-bit device drivers’. In order to 


insure continued support, the drivers should be written with currently 


available and supported 32-bit tools such as Visual Age C++ for OS/2 and 


the Microsoft 32-bit macro assembler. 


To allow OS/2 to be used in a network configuration, perhaps in a diskless 
mode, the system must be able to dynamically load device drivers as 
needed from a local disk or from a server. This is a major change in the 
way OS/2 operates today. Currently, all device drivers are loaded at boot 
time, and are specified in the special CONFIG.SYS file. Adding or deleting 
a driver from the system requires that the CONFIG.SYS file is edited and 
the system rebooted to effect the change. Therefore, we regard the 
dynamic device driver-loading feature to be an integral part of our 
requirements and necessary for the successful implementation of our 


design. 
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Chapter 1. - Introduction 


Problem 

OS/2 device driver development is at a standstill. The OS/2 device driver 
model was derived from a DOS device driver model. It retains much of the 
16-bit architecture of the 16-bit Intel 80286 processor on which was first 
implemented in OS/2 1.0. Since that time, the mainstream Personal 
Computer (PC) processor has grown from a 16-bit architecture to a 32-bit 
architecture. Since the newer processors are backward compatible, the 
older driver software still runs without change. However, 16-bit compilers 
for OS/2 are no longer available, stunting the growth of new driver 
development. The mixed mode of 16-bit and 32-bit interfaces makes driver 
development difficult, and programmers spend too much time creating 


specialized code to handle the address conversions. 


Purpose 

The purpose of this study is to identify the amount of work necessary to 
convert existing 16-bit device drivers to 32-bit device drivers, and to 
provide a framework for new device driver development using 32-bit tools. 
It should be noted that this proposal describes the changes necessary to 
convert existing 16-bit device drivers to 32-bit, and to allow new 32-bit 
drivers to co-exist with the older model. While it would have been easy to 
design a new model based on current technology such as the I2O 
initiative, the goal of this proposal was to preserve the investment in 


current device driver development and training. 


Importance of Study 

This study will help determine if converting existing 16-bit device drivers to 
32-bit is feasible, and if the return on programming investment is worth the 
effort. The data gathered, along with the conclusions, will determine the 


level of funding and programming resources to allocate. 


Scope of Study 

This proposal suggests a new device driver model for the OS/2 operating 
system, and as such, contains several design suggestions and criteria that 
are specific to OS/2. OS/2 is a hybrid system, part 16-bit and part 32-bit. 
Many of the functions or methods used or presented in this design are 
specific to the OS/2 operating system, and therefore not necessarily valid 


or applicable for other operating systems such as Windows NT or Unix. 


Rationale of Study 

Since the OS/2 device driver development environment can be 
problematic, we decided that the best way to verify our design was to 
actually implement it. Many design flaws or omissions occur only under 
load, in actual operating conditions, especially those issues related to 
timing, race conditions, or interrupt latency. By using real working device 
drivers, we felt that we could expose these problems more quickly than 


any other method. 


Definition of Terms 
API. Application Programming Interface, a definition of what external 


functions are available to a program and how to call them. 


Arbitrate. In programming terms, the ability of the device driver to act as a 


“traffic cop” to grant or deny hardware access to an application. 


Abstract (verb). In programming terms, the verb abstract means to “hide 
the details”. A device driver abstracts or “hides the details” of the low-level 


device architecture from the application software. 


Device Driver. The software program that acts as the interface between 
an application program and a hardware device. The device driver is 
responsible for converting high-level requests from the application 


program into low-level commands that the hardware can understand. 


DMA. Direct Memory Access, a method of transferring data to and from 


memory by using a specialized piece of hardware. 


Dynamic Linking. An architecture that allows external references to be 
resolved at program load time. This results in smaller executables but a 


slightly longer initial load time. 


File System. The internal subsystem in an operating system that controls 


access to hardware devices. 


Flat Model. A term that describes a 32-bit addressing mode in which the 
address contains the actual memory page information and offset. The 
processor hardware decodes the physical page information. Flat pointers 


can directly access up to 4GB of memory. 


Hardware. The physical electrical components of the computer system or 


device interface. 


Legacy Devices. A term used to denote older devices and their support 


hardware. These devices are usually ISA bus devices. 


Multiprocessor. A computer architecture where the computer is equipped 


with more than one Central Processing Unit (CPU). 


Polling. A programming method that involves waiting in a tight loop for a 
particular bit to change state or a particular event to occur. Polling results 
in inefficient use of the processor cycles because other programs are 


prevented from running while polling is being performed. 


Protect Mode. A specific mode of operation for the Intel 80x86 series of 
processors that provides for hardware-based memory protection and a 32- 


bit flat memory architecture. 


Real Mode. A specific mode of operation for the Intel 80x86 series of 
processors that provides a one-megabyte memory size with no memory 


protection. MS-DOS runs in real mode. 


Segment:Offset. A method of memory addressing for the Intel 80x86 
series of processors that forms a 32-bit address from a 16-bit selector and 
a 16-bit offset. The selector is actually an index into a table of memory 
descriptors that contain the physical page number and access rights of the 
memory. The offset portion is only large enough to describe a 64K 


segment of memory. 


Spinlock. A specialized program loop that prevents other operations or 
programs in the system for being executed while the special loop is being 


executed. 


Thunking. The process of converting 32-bit pointers to their 16-bit 
equivalents, and 16-bit pointers to their 32-bit equivalents. Thunking from 


32 to 16 can be very time-consuming. 


Overview of the Study 

Early Personal Computer (PC) operating systems such as MS-DOS were 
single tasking, i.e.; they were capable of executing only one program at a 
time. Even though these systems were somewhat slow, they were still 
much faster than the devices they needed to access. Most output 
information was sent to a line printer and most input data was read from a 
keyboard. If a program needed to perform input or output (I/O) to one of 
these devices, the system would effectively remain idle while waiting for 
the data to be sent or entered. This method of performing I/O, called 
polling, was very inefficient. Even though the computer was capable of 
executing thousands of instructions in between each keystroke, it was 
kept busy while I/O was being performed. If a program needed to print 
something on a printer, it would send the data one character at a time, 
waiting for the device to acknowledge that the character was accepted 
before sending the next character. Since the computer processed the data 
faster than it could be printed, it would sit idle for much of the time waiting 


for the printer to do its job. As technology progressed, faster I/O devices 


became available, but so did faster computers. The computer was at the 


mercy of the input and output devices it needed to access. 


The problem was exacerbated by the fact that each one of these I/O 
devices required data in a different form. Some devices required data in a 
serial fashion, bit by bit, while others required data 8 or 16 bits at a time. 
Some line printers printed on 8 1/2 by 11-inch paper and some on 11 by 
14-inch paper. Magnetic tape storage devices used different size tapes 
and formats, and disk storage devices differed in both the amount and the 


method of storage. 


The device driver solved the problems associated with the different types 
of devices, and provided a more efficient method of utilizing the 
processing power of the computer while it was performing input and output 
operations. The device driver is a small program inserted between the 
program performing the I/O and the actual hardware device such as a 


printer or magnetic disk drive. 


The device driver is programmed with the physical characteristics of the 
device, and acts as an interface between the program and the device. For 


example, the device driver for a line printer might be programmed with the 


characteristics of the printer, such as the number of characters per line or 
the size of the paper that the device supports. The device driver for a 
magnetic tape drive might be programmed with the physical 
characteristics of the tape mechanism, such as the tape format and 
density. The ability of the device driver to hide or abstract the details of a 
hardware device is a fundamental concept in the design of today’s 
operating systems and applications software. Programmers writing 
software do not need detailed knowledge of the devices that the program 
may use, and do not have to provide specialized programs to access 
those devices. For example, the software for an application that needs to 
send data to a printer can be written the same way no matter what type of 
printer is installed on the system. The same data can be sent to a high- 
resolution laser printer or a low-resolution dot-matrix printer with the same 
results. Old printers can be deleted, or new types of printers added without 


the need to change the application software. 


Device drivers also address the problem of polling. Since the device driver 
has intimate knowledge of how to deal with the hardware, there is no 
reason why the application program has to wait around for each character 
to be printed. It can, for example, send the device driver a block of 256 


characters and return to continue executing the application program while 


the device driver handles the details of sending the data to the device. 
When the device driver finishes sending all the data, it notifies the 
application program that it needs more data. The application then sends 
the next block of data to the device driver for processing. While the device 
driver is performing the I/O, the application can continue processing data 
or performing other operations. This results in more efficient use of the 


system processor. 


The use of device drivers became even more important when operating 
systems such as Windows and OS/2 appeared that could run more than 
one program simultaneously. In systems that can run many programs at 
the same time, it is possible that more than one program might try to 
access a hardware device at the same time. The device driver performs 
an important function by controlling access to the hardware device. In 
some cases, such as a printer, the device driver serializes or arbitrates 
access to the device so that one program’s output does not appear in the 
middle of another program's output. Once the printer has begun servicing 
a program, subsequent attempts to access the printer are refused, and the 
“busy” indication is sent back to the requesting program. The requesting 
program can then decide to wait for the printer to become available or to 


access the printer at a later time. 


Device drivers are an irreplaceable and critical link between the operating 
system and the I/O device (see Figure 1-1). They can interact directly with 
the Central Processing Unit (CPU) and operating system, and in some 
cases, can allow or block the execution of programs. Device drivers 
usually operate at the most trusted level of system integrity, so the device 
driver writer must test the driver code thoroughly to assure bug-free 
operation. Failures at a device driver level can be fatal causing the system 


to crash or experience a complete loss of data. 
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Figure 1-1. The Role of the device driver. 


The use of computers for graphics processing has become widespread. It 
would be impossible to support the many types of graphics devices 
without device drivers. Today’s hardware offers dozens of different 
resolutions and sizes. For instance, color graphics terminals can be had in 
pixel sizes of 800 by 600, 1024 by 768, 1280 by 1024, and as high as 
2048 by 2048. Each resolution can support a different number of bits per 


pixel, or color depth. 


Printers vary in dots per inch (DPI), font selection, and interface type. 
Since all of these formats and configurations are in use, the supplier of a 
graphics design package that needs to send data to a printer would have 
to support all of the configurations in order to offer a marketable software 
package. A graphics application program might direct the output device to 
print a line of text in Helvetica bold italic beginning at column 3, line 2. 
Each graphics output device, however, might use a different command to 
print the line at column 3, line 2, so the device driver resolves these types 
of differences. Instead of having to write, debug, and support all of these 
special device drivers, the graphics application reads from and writes to 
these graphics devices using a standard set of APIs, which in turn call the 
device driver specific to the device currently installed. Without this 


standardized interface, the software vendor would be forced to supply 


device drivers for the hundreds of different types of input and output 
devices. Some word processors, for example, would be forced to supply 
hundreds of printer device drivers to support all makes and models of 
printers, from daisy wheel to high-speed laser and color printers. 


In summary, the device driver: 


* Contains the specific device characteristics and removes any 
responsibility of the application program for having knowledge of 


the particular device. 


¢ Allows for device independence by providing for a common 
program interface, allowing the application program to read from or 
write to generic devices. It also handles the necessary translation 


or conversion that may be required by the specific device. 


* Serializes access to the device, preventing other programs from 
corrupting input or output data by attempting to access the device 


at the same time. 


¢ Protects the operating system and the devices owned by the 
operating system from errant programs which may try to write to 


them, causing the system to crash. 


OS/2 Overview 

OS/2, introduced in late 1987, was originally called MS-DOS 4.0. It was 
later named MS-DOS 5.0, and finally OS/2. OS/2 was designed to break 
the MS-DOS 640KB real mode memory barrier by utilizing the protect 
mode of the 80286 processor. The protect mode provided direct 
addressing of up to 16 megabytes (MB) of memory and a protected 
environment where badly written programs could not affect the integrity of 


other programs or the operating system. 


The Intel processors are capable of operating in one of two modes. These 
are called real mode and protect mode. One of the most popular computer 
operating systems, MS-DOS, runs in real mode. In real mode, the 
processor is capable of addressing up to one megabyte of physical 
memory. This is due to the addressing structure, which allows for a 20-bit 


address in the form of a segment and offset (see Figure 1-2). 
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Figure 1-2. Real mode address calculation. 


Real mode allows a program to access any location within the one- 
megabyte address space. There are no protection mechanisms to prevent 
programs from accidentally (or purposely) writing into another program’s 
memory area. There is also no protection from a program writing directly 
to a device, say the disk, and causing data loss or corruption. MS-DOS 
applications that fail generally hang the system and call for a <ctrl-alt-del> 
reboot, or in some cases, a power-off and a power-on reboot (POR). The 
real mode environment is also ripe for viruses or other types of sabotage 
programs to run freely. Since no protection mechanisms are in place, 
these types of “Trojan horses” are free to infect programs and data with 


ease. 


The protect mode of the Intel 80286 processor permits direct addressing 
of memory up to 16MB, while the Intel 80386 and 80486 processors 
support the direct addressing of up to four gigabytes (4,000,000,000 
bytes). The 80286 processor uses a 16-bit selector and 16-bit offset to 
address memory (see Figure 1-3). A selector is an index into a table that 


holds the actual address of the memory location. 
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Figure 1-3. 80286 protect mode addressing. 


The offset portion is the same as the offset in real mode addressing. This 
mode of addressing is commonly referred to as the 16:16 addressing. 
Under OS/2, the 80386 and 80486 processors address memory using a 
linear address. The linear address is a 32-bit flat address consisting of 


three parts. The first part, which is 10 bits long, is an index into a page 


table referred to as the PTE. The second part, which is also 10 bits long, 
specifies a particular page frame within the page table. The third part is an 
offset into the page frame. The page information is decoded by the paging 
hardware located on the processor. The physical address is formed by 
locating the PTE, indexing to the correct page frame, and adding in the 
offset portion of the address. This mode of addressing is referred to as the 


0:32 or flat addressing (see Figure 1-4). 
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Figure 1-4. 80386 linear addressing. 


The protect mode provides for hardware memory protection, prohibiting a 
program from accessing memory owned by another program. While a 
defective program in real mode can bring down the entire system (a 
problem frequently encountered by systems running MS-DOS). A protect 
mode program that fails in a multitasking operating system merely reports 
the error and is terminated. Other programs running at the time continue 


to run uninterrupted. 


To accomplish this memory protection, the processor keeps a list of 
memory belonging to a program in the program's Local Descriptor Table, 
or LDT. When a program attempts to access a memory address, the 
processor hardware verifies that the address of the memory is within the 
memory bounds defined by the program’s LDT. If it is not, the processor 


generates an exception and the program is terminated. 


The processor also keeps a second list of memory called the Global 
Descriptor Table, or GDT. The GDT usually contains a list of the memory 
owned by the operating system, and is only accessible by the operating 
system and device drivers. Application programs have no direct access to 


the GDT except through a device driver. 


OS/2 was designed with several goals in mind. First, OS/2 had to provide 
a graphical user interface that was consistent across applications and 


graphics hardware. 


Second, OS/2 had to support Dynamic Linking. With Dynamic Linking, 
some functions required by an application can reside in a separate file, 


which is loaded only at run time. This feature makes application file sizes 


smaller, allows more than one client to use the Dynamic Link Library 
(DLL), and allows functionality to be placed in the DLL without changing 


the application code base. The majority of OS/2 is implemented in DLLs. 


Third, OS/2 had to provide an efficient, preemptive multitasking kernel. 
The kernel had to run several programs at once, yet provide an 
environment where critical programs could get access to the CPU when 
necessary. OS/2 uses a priority-based preemptive scheduler. The 
preemptive nature of the OS/2 scheduler allows it to “take away” the CPU 


from a currently running application and assign it to another application. 


OS/2’s smallest granularity of execution is the thread, which is an 
instance of execution. Processes consist of one or more threads, and 
each thread can execute at its own priority. OS/2 has four priority classes 
with 32 levels within each priority class. Threads with higher priority can 


interrupt the execution of lower priority threads. 


Fourth, OS/2 had to provide a robust, protected environment with virtual 
memory. OS/2 uses the protect-mode of the 80286 and above processors, 
which has built-in hardware memory protection. Applications that attempt 


to read or to write from memory that is not in their specific address space 


are terminated without compromising the operating system integrity. OS/2 
uses an efficient memory allocation and paging scheme consisting of a 
combination of first-fit, Least Recently Used (LRU), and compaction to 


minimize fragmentation. 


Fifth, OS/2 had to support the older 16-bit protect-mode applications that 
used the segment:offset addressing scheme as well as new, 32-bit flat 
model executables. OS/2 offers a rich set of Application Program 
Interfaces (APIs) to allow programs to access system services. The OS/2 
APIs are classified into eight major categories; file systems, graphics 
interface, inter-process communications, systems services, 
process/thread management, memory management, signals, and dynamic 


linking. 


Finally, OS/2 had to run most MS-DOS programs in an MS-DOS- 
compatibility mode. OS/2 allows MS-DOS programs to run in their own 
one megabyte of virtual memory space, providing protection from other 


MS-DOS or OS/2 programs. 


At the time OS/2 was written, the most powerful mainstream processor 
available for the PC market was the Intel 80286. At that time, memory was 
still quite expensive, and most PC systems were shipped with a maximum 
of 4MB of memory installed. Accordingly, the operating system and 
support code was written using 16-bit tools that produced smaller and 
faster code. Because of space and speed considerations, a majority of the 


OS/2 kernel and supporting DLLs were written in assembly language. 


After Microsoft and IBM split on the direction for OS/2, IBM embarked on a 
project to convert 16-bit OS/2 into a 32-bit operating system. This was 
now possible for two reasons. First, the mainstream processor shipped 
with Intel-based PCs was the 80386, a full 32-bit processor. Second, the 
price of memory had dropped dramatically, and most systems were now 


shipped with up to 8MB of memory’. 


During this conversion, IBM elected to make a radical change in the user 
interface rather than to rewrite the OS/2 kernel. This was done for two 
reasons. The first was that like most companies, they had limited 


programming resources that could be brought to bear on the rewrite. The 


second reason was that OS/2 device drivers were difficult to write, and 
IBM wanted to retain support for any existing 16-bit device drivers that had 
already been written. All of the system’s internal data structures were byte 
or word aligned, the scheduling, dispatching, and virtual memory data 
structures were all written in assembly language, and accessed via 16-bit 
selector:offset addresses. The file system, the heart of the device driver 
interface, was also written entirely in 16-bit code. IBM made the decision 
to work on the area of OS/2 that would make the most visual impact while 
leaving all of the internal plumbing untouched. This turned out to be a 


serious long-term error in judgement. 


For tools, IBM used the Microsoft 16-bit assembler and Microsoft 16-bit C 
compiler. For the few 32-bit components that were part of OS/2, IBM used 
an unreleased 32-bit version of Microsoft's C compiler. Worse, some 
components would compile and link only with certain versions of the 
assembler or compiler. Microsoft, seizing a golden opportunity, 
discontinued the availability of the 16-bit tools and never released the 32- 
bit version of their 32-bit C compiler. This brought a grinding halt to 
mainstream device driver development, relegating it instead to a few 


independent driver development shops that still had a license to the old 


tools. Today, almost seven years later, OS/2 still suffers from those fateful 


decisions to leave the file system and device driver interface untouched. 


The Proposal 

This proposal suggests a new flat-model base device driver model written 
in C. Appendix A also suggests a new base driver model written in C++ 
utilizing Object Oriented (OO) design techniques®. OO purists may find 
some of the C++ code and techniques objectionable because they don’t 
adhere to a strict OO paradigm. However, it is our observation that 
interaction directly with the hardware requires a somewhat procedural 
approach, even if an object oriented language is used. Using C++ 
presents some possible problems, such as the timely collection of dead 
objects from the system heap. In OS/2, the system heap is swappable, 
which may lead to several page faults when destructors are called or 


during system heap compaction. 


We have chosen C because of its universal acceptance and its ability to 


easily perform low-level functions. In Appendix A, we present a sample 


driver written in C++. Although some C++ programmers may find this 
model more “comfortable”, we see no advantage in using C++ over 
conventional C. The allocation of objects in a device driver is usually done 
at load time, and the resources remain locked while the device driver is 
loaded in memory. If, for example, the driver needed to access a buffer at 
interrupt time, it would not be possible to allocate the buffer or swap it in 
off the disk in time to service the interrupt, so the buffer must remain in 
memory. Also, C++ calls object destructors automatically, which might 
result in an object going out of scope at just the wrong time. This could 
cause intermittent or fatal errors, and would be difficult to track down. A 
feature of C++ is the ability to return to the heap the space that was 
allocated by objects that have since gone out of scope. The ability to 
perform timely garbage collection and heap compaction can be critical for 
the proper operation of a C++ device driver. Because there are some 
issues related to C++ that we are not sure can be easily solved, we 


decided to use C for the purposes of this design. 


Our proposal intends to solve the following problems: 


1. Currently, device drivers are loaded in the order that they appear in the 
CONFIG.SYS file. This can cause conflicts in certain hardware 
configurations where port or memory addresses may overlap. 

2. In the current implementation of OS/2, no file I/O services are available 
from within the driver’. There is no method of logging activity or events 
during driver execution. 

3. There are no profiling services available at the driver level. 

4. There are virtually no supported 16-bit compilers and assemblers with 
which to build new device drivers. 

5. Device drivers are currently unable to allocate more than 64KB of 
contiguous physical memory. 

6. To use DMA, the driver must write directly into the 8237 DMA 
controller registers, perform several memory allocations until a memory 
object is allocated on the correct segment boundary and paragraph 
alignment, and double-copy data if the application buffer is above the 


16MB boundary”. 


7. Device drivers are loaded statically by references in the CONFIG.SYS 
file. The drivers must be able to be loaded dynamically or “as needed”. 
8. Drivers are loaded in low memory, below the 640KB boundary limiting 


the size and number of device drivers that can be loaded at boot time. 


To satisfy these requirements, we have made the following assumptions: 


1. The file system will be rewritten to handle the proper device driver 
calls. This might include a 32-bit to 16-bit thunk layer or memory 
aliasing to provide a seamless interface to the 32-bit device driver. In 
other words, the 32-bit device driver should be able to be installed, 
configured, run, and deinstalled without being aware if the underlying 
architecture is 16-bit or 32-bit. 

2. The file system will be modified to accept long device names. 
Currently, OS/2 supports only 8 character device names, a relic from 
the old 8.3 file naming conventions. 

3. The system will be modified to support a persistent data store or 


registry for supported devices, either installed or uninstalled. 


. The system will correctly handle mapping or aliasing pointers passed 
by 16-bit applications inside the request packet. It is the programmer's 
responsibility to handle any imbedded pointers in private data buffers 
shared between the application and the device driver. 

. The system will be modified to add the Delnstall command that 
removes the driver from the system, freeing up any resources owned 
by the driver®. 

. OS/2 will provide a configuration utility to examine and modify the 
persistent configuration store or registry to permit legacy device 
settings to be stored. 

. OS/2 will be modified to allow access to the least significant bits of the 
8254 timer to provide a reasonable granularity for the driver profiling 
services. 

. The OS/2 system loader will be modified to load the new device driver 
model. This loader should operate both at boot time and later when a 
device driver is dynamically loaded. We think this effort will be a major 


task. 


9. Wherever possible, the new driver model shall incorporate code, 
functions, subroutines, and macros from the existing 16-bit device 
driver model to ease the conversion of older drivers. The conversion of 
older drivers should be easy and straightforward, and if possible, 


should follow the architecture of the existing 16-bit model’. 


Chapter 2. - Review of Related Literature 


Requirements 

During boot, the system will enumerate the system hardware to determine 
the current configuration. The current configuration will be compared to 
the last good configuration from the persistent store. If the information is 
different, the appropriate event mechanism will be started’. If the boot 
process is successful, the old configuration information should be backed 
up to a file, and the new configuration should become the current 
configuration. The system should always keep a known good configuration 
in the event of a system crash or corruption of the configuration persistent 
store. If a corrupt configuration file is encountered during boot, the user 
should be given the choice of using the last known good configuration or 
loading a new configuration from a file on floppy disk or hard disk. This 
operation is already performed by many popular operating systems such 


as Windows NT. 


The device driver model will support the ability to be dynamically loaded, 


configured, and removed, and the system should automatically scan the 


machine to determine if any devices have been added or removed 
(Shanley, 1995). The system should attempt to detect legacy devices as 
well as enumerating Plug and Play devices, PCI devices, and devices on 
other bus types such as Universal Serial Bus (USB). A good example of 


how this is performed can be observed in Windows 95. 


In addition to detecting devices and bus types at boot time, a system- 
based configuration manager or “sniffer” will be periodically run. Many of 
these devices support hot (power on) insertion and removal, so that 
perhaps every five to ten seconds or so, the configuration manager will 
attempt to determine if a new device has been inserted or an existing 
device removed. If the system detects that a new device has been 
installed, it looks up the configuration information for that device in the 
system's device configuration table. If the configuration information is 
located, the configuration manager attempts to find and load the device 
driver associated with the device, and calls the initialization section of the 
device driver to perform its configuration process. If the device 
configuration information is not found in the system’s configuration table, 


the user is prompted to insert a diskette or path information to where the 


configuration information is located. The appropriate data is copied to the 
system’s persistent store, and the configuration process begun. If the 
configuration process fails, the device driver is unloaded, and any 


resources claimed so far are automatically released”. 


Some devices cause immediate detection events, such as the insertion or 
removal of a PCMCIA card. Upon insertion of a PCMCIA card, the 
configuration data is read from tuples located in the PCMCIA card and 
compared with the persistent registry data (Mori, 1994). If the 
configuration information for the card already exists, the system loads the 
necessary driver and calls the driver's initialization code. The initialization 
code then configures the card using the configuration manager. Our 
proposed model supports older 16-bit PC cards as well as 32-bit CardBus 
PCI implementations (Anderson & Shanley, 1995). CardBus adapters can 
allocate 32-bit flat memory in any region of the PC memory address 


space. 


The system registry must be able to support legacy devices whose 
resources are configurable only through jumpers or switches, or via a 


proprietary programming sequence (Kelsey, 1995). Some older devices 


require the booting of a MS-DOS diskette to download software to the 
adapter or configure the adapter’s resources such as interrupt level, 
memory mapped address, DMA channels, or port addresses. The system 
registry utility is used to examine and manually enter the resources 
required by the legacy device. If the user attempts to claim a resource that 
is already in use, the request is refused"®. In some cases, it will be 


necessary to write a “sniffer” that is specific to the particular device. 


Addressing 

Wherever possible, the system should avoid thunks. In particular, 
converting or thunking 32-bit addresses to 16-bit addresses are difficult to 
implement because the 32-bit pointer can cross 64KB boundaries (Deitel 
& Kogan, 1992). To avoid unnecessary thunks, the device driver interface 
should be implemented in 32-bit code, not thunked to their 16-bit 
counterpart. This will certainly cause the size of the kernel to grow, but the 
increased performance should more than make up for the larger kernel 
size or execution time. In a resource-constrained environment, it may be 
appealing to simply insert thunks for the 32-bit APIs. While this will save 
initial coding work, we believe it will have a significant impact on system 


performance. 


Legacy Support 

Although the system should provide seamless, flat-model interfaces to 
services and data structures, a few exceptions must be provided for. One 
of these exceptions is the support of scatter-gather lists for those devices 
that export only 24 address lines. Some SCSI adapters require that they 
perform reads and writes to certain physical addresses. Because the 
adapter recognizes only 24 bits of address, those physical addresses 
must reside below the 16MB boundary. Another exception to the exclusive 
use of 32-bit pointers is the use of Direct Memory Access, or DMA. The 
DMA hardware in most systems is a holdout of the ISA bus architecture, 
and is thus limited to 24 bits of address. Adapters that perform DMA reads 
and writes must use data buffers that are below the 16MB boundary. If the 
application is running above the 16MB boundary, the system must provide 
the ability to copy the data from the buffer below the 16MB boundary to 
the application’s buffer in high memory. The device driver interface should 


do this transparently via a device driver service. 


Current OS/2 segmented device drivers contain at least one code 
segment and one data segment, and are loaded in low physical memory 
(Deitel & Kogan, 1995). The new kernel must allow the new 32-bit device 


drivers to be loaded anywhere in physical memory, and not restrict them 


to any particular region'’. In addition, the current 16-bit driver model 
restricts interrupt and timer handlers to the first code segment. Our 
proposal assumes that no such limitation will exist. The system should 
have the maximum flexibility in choosing how to distribute interrupt 
requests and should support Advanced Priority Interrupt Controller (APIC) 


if present (Anderson & Shanley, 1995). 


The new device driver model should support a symmetric 
multiprocessor (SMP) configuration. Writing a device driver for an MP 
system requires care, just as it requires care to write an application for a 
multiprocessor system. Global variables should be avoided wherever 
possible (IBM, 1993), and platform-specific APIs for low-level access 
should be called rather than accessing the hardware directly. Although 
there may be some performance gain in bypassing the published 
hardware interfaces, the result will be code that runs on one particular 
platform but not another. Proper operation in an MP system requires 
serialized access to hardware and software resources. Manipulating 
hardware directly could cause these serialization functions to be 


ineffective, and introduce intermittent bugs and system failures that would 


be nearly impossible to locate. Race conditions are normal in an MP 
system. A thread blocked on one processor can be restarted on another 
processor or swapped out to disk at the system's discretion. Failing to 
adhere to the correct procedures could cause the system to become 
unstable and ultimately fail. All functions and subroutines for the new 


driver model shall be made MP safe. 


Extreme care must be exercised when using global variables. Since 
device driver operations usually happen asynchronously, a condition might 
occur where two routines or functions attempt to access the global 
variable at the same time. Normally, global variables accessed by an 
application are protected by some type of semaphore mechanism to 
prevent this from happening. However, the device driver operates in 
kernel mode of the processor, and the semaphore functions are not 
available in kernel mode. One reason for this is that the OS/2 driver, while 
in kernel mode, is interruptible but not preemptible. While the OS/2 device 
driver is running it can be interrupted by an external device interrupt but it 
can not be suspended in favor of another higher priority device driver. This 
means that while the OS/2 device driver is executing, no other system 


service or program can be running. 


The use of global variables becomes even more critical when the device 
driver is operating in a system with multiple processors. If a device driver 
becomes blocked on one processor, it can be restarted on another 
processor when a particular event occurs. OS/2 solves this by reflecting all 
interrupts to CPUO, while Windows NT uses a ring-0 semaphore 
mechanism called a spin-lock. Our proposal suggests a design where the 
device driver uses an object-oriented strategy by eliminating most global 
variables and encapsulating the variables inside functions. Real 
encapsulation is not possible at the driver level since we do not actually 
create an object in the traditional sense, but the function will access global 
variables that only the particular function is aware of. Since only one 
thread of the driver code can be executing at a time, this method provides 
serialized access to those variables. We believe that by adopting this 
strategy, all device drivers will be inherently MP-safe, providing they follow 


all the other guidelines for safe MP operation. 


Chapter 3. - Methodology 


Approach 

Our approach involved the conversion of three specific device drivers from 
16-bit to 32-bit. We felt that this was the best method, as we would have 
an existing model against which to verify our results and benchmark 
performance. Complete program listings of the three device drivers before 


and after conversion can be found in Appendix A. 


Method and Database of Study 

To validate our proposed design, we converted three existing 16-bit device 
drivers to the new 32-bit design. Because our design requires several 
other changes to the OS/2 kernel that may not be finished at the time we 
will be ready to begin testing, we were forced to simulate some operations 
in software. We built a software simulator that calls the device driver 
functions and executes as much code as possible. To monitor execution 
time, we took a snapshot of the millisecond timer upon entry into the 
device driver and another snapshot when exiting. While we could not test 
every execution path, this data did give us a general idea of execution 
time. While this was certainly not an optimal solution, it was possible to 
test the basic architecture of our design and compare some results with 


older 16-bit device drivers. 


Validity of Data 

Since we used three actual device drivers for our conversion, we believe 
the data contained herein to be valid, at least for these three cases. Since 
many components were not finished or installed at the time of our study, it 
was impossible to guarantee that we had uncovered all of the problems 
associated with the conversion. We have attempted to point out these 
unknown issues throughout this document, and have summarized them in 


Chapter 5. 


Originality and Limitations of Data 

Since the concept outlined in this document has never been attempted, 
data associated with the proposal has never been collected. While some 
general concepts, such as decreased performance and larger executable 
size are generally known and accepted, the actual application of those 


concepts in our proposal has not been previously documented. 


It would have been easy to start with an entirely new device driver model, 
but this would render existing device drivers useless. The challenge is to 
provide an enhanced architecture while still maintaining backward 
compatibility with the hundreds of current OS/2 device drivers. This 


proposal suggests an architecture for the OS/2 base device driver model 


only. OS/2 uses several other types of device drivers, but most have 


already been converted to 32-bit models so they are not covered here. 


Summary 

The object file format of the device driver is the same as a DLL, so we 
loaded the device driver as a DLL for testing purposes. It was impossible 
to test real timer or device interrupts, since interrupts are only available in 
ring 0 and the DLL loads at ring 2. The simulator made calls to the timer 


and interrupt handlers to test their correct operation. 


We encountered several problems and oversights with our initial design 
during the preliminary testing process. Some of these problems caused us 


to revise our design, and others required further system changes. 


One concern that had been expressed to us is the fear that our design 
would cause the size of the installed imaged to grow very large. Indeed, 
our past experience had shown that converting 16-bit code to 32-bit code 
resulted in large increases in executable code size, sometimes in excess 
of 100 percent. We took no extra steps to optimize the executable size by 
changing the way we wrote the code to insure the comparisons with the 


16-bit executables were valid. 


During our testing, we noted the size increases for our new drivers and 


support software. They are discussed in detail later in Chapter 5. 


Existing 16-bit device drivers primarily use 16-bit selectors and 16-bit 
offsets to form 32-bit addresses. Address and pointer conversions in 16-bit 
mode are very fast, especially when the memory range is equal to or less 
than 64KB. We expected that direct addressing using 32-bit pointers 
would be faster, especially since we could utilize the native block moves in 


the Intel processor. Our results are summarized in Chapter 5. 


Drivers frequently create 32-bit alias pointers which point to other areas in 
memory, such as user buffers or memory-mapped areas of a device. The 
driver calls a system function to map a 16 or 32-bit physical address to a 
virtual or user virtual address. During this conversion, the system allocates 
a 32-bit selector from the pool of 32-bit selectors. Since OS/2 was 
designed to handle both 16-bit applications and 32-bit applications, we 
were unsure if the current pool of selectors available for allocation would 
be large enough, or contained enough 32-bit selectors to accommodate 
our new design. We wrote some test code to determine the number of 


selectors necessary. 


In OS/2, application programs do not call device drivers directly. Instead, 
they call a system API that in turn calls the device driver through an 
established interface. This interface performs initial parameter validation 
and provides the ring transition from user mode to kernel mode and back. 
The communication medium between the APIs and the device driver is 
called the Request Packet. The request packet contains the operation 
code and parameters associated with the request such as pointers and 
data. OS/2 allocates a limited number of request packets, based on the 
available memory in the system heap space, so we were unsure that that 
OS/2 was allocating enough space for the packets. We later concluded 
that the system should provide up to 512 16-bit packets and 512 32-bit 
packets to insure that enough packets were available for even the largest 


number of devices. 


In OS/2, the device header structure contains pointers to functions located 
in the device driver. It is a static structure created at compile and link time, 
and provides entry points for the initialization and strategy sections of the 
device driver. In the current implementation of OS/2, these pointers are 
kept only as 16-bit offsets since the driver model is 16-bit. With a flat 


model, these pointers will become 32-bit flat addresses. Programs or 


system components that need to call the device driver functions do so by 
locating the address of those functions from the driver’s header 
information. These system components need to be changed to refer to the 
address values correctly. We will insert a special bit in the device header 
to indicate the driver is a new flat model driver, and that addresses should 


be assumed to be linear. 


The request packet contains pointers to buffers and data items that are 
located in the application program address space. Even though the driver 
is a 32-bit implementation, it is possible that the application that needs to 
access the device driver is still 16-bit. The system and device driver will 
allow these programs to be used by transparently handling any address 


conversions or address mapping. 


Chapter 4. - Analysis of the Problem 


How We Tested 

For our first conversion from the 16-bit model to the new flat model, we 
decided to start with a simple device driver that is used to access the 
parallel port called MMAP.C (see Appendix A — Listings). Programmers 
have frequently used this public domain device driver as a basis for 


learning how to write OS/2 device drivers”. 


The device driver contains the two main sections of an OS/2 device driver, 
the Initialization section, and the Strategy section. In order to keep the 
device driver simple; the driver does not contain an interrupt handler or 


timer handler (See Appendix — Listings). 


We began by identifying the variables that needed to be converted to 
accommodate our new model. Before modifying the driver variables, we 
decided to start with the local header files (see Appendix A - Listings) that 


are included by the device driver. 


While operating in the 16-bit mode, the instruction set of the Intel 
processor allows two distinct types of addresses. To access data or 
instructions within a particular 64KB segment, a program can use near 
addressing. Near addressing assumes that the code or data being 
accessed resides in the same segment that is currently selected. Since 
the same segment is used, the only portion of the address that needs to 


change is the 16-bit offset. 


Far addressing allows access to code or data anywhere within the 16MB 
memory area. In far addressing, the pointer contains a segment as well as 
an offset. Like near addressing, the offset portion specifies an address 


within a 64KB segment. 


A 32-bit flat model program makes no distinction in addressing modes. All 
pointers and addresses are 32 bits long, and are referred to as linear 
addresses. In fact, the 32-bit C and C++ compilers do not allow the use of 
the common 16-bit modifiers near and far, so we began by deleting all of 


the near and far modifiers in the header files. For purposes of readability, 


we also deleted any references to the data tyoe FARPOINTER, including 


any instances where FARPOINTER was used in function prototypes'®. 


Header File Conversion 

To avoid unnecessary duplication of 32-bit data types, we began by 
changing all of the unsigned short variables in the structure definitions to 
standard 32-bit data types defined in the 32-bit compiler’s header files. 
Variables that contain pointer data types are automatically expanded to 
32-bits by the compiler when the compiler-defined pointer data type is 
used in the declaration. We also made sure that any variables that were 
not defined as pointers but that might hold a pointer temporarily were 


converted to 32-bit variables (see Appendix A - Listings). 


We then converted any variables defined as BYTE or unsigned character 
to 16-bit. The reason we did this is that the compiler will attempt to 
optimize the storage of data structures by packing bytes together in 
adjacent memory locations. The data in the variables is sometimes 
passed by reference to another device driver or application. That is, the 


driver may send a pointer to the data structure to another device driver or 


application. The receiving driver or application may attempt to de- 
reference the pointer using a 16 or 32-bit pointer type, so the data must be 
word-aligned. Although we knew that memory requirements would be 
increased because of the larger data types, we felt that it was better to 
increase the memory size than to spend time debugging misaligned data 
structures. Unfortunately, we had to reverse this operation because we 
could not be sure that the system-level variables defined by these fields 


would be changed. 


We then changed the system library function prototypes from NEAR 
PASCAL to PASCAL. The PASCAL parameter passing method is much 
easier to implement because a fixed number of parameters must be 
passed and the caller does not have to worry about cleaning up the stack. 
This makes even more sense because the device driver does not own the 
stack; therefore the device driver cannot manipulate the stack or stack 


pointer. 


Driver Code Conversion 
When we finished converting all of the header files, we began converting 
the variables in the device driver. OS/2 device drivers usually contain two 


types of variables, global and local. Global variables exist outside the C 


source code, and can be accessed by any function or subroutine in the 
device driver. Local variables are variables created within a particular 
function. Local variables are stored on the stack. We converted all of the 
pointers to the correct type, and then began changing some of the driver’s 
internal structures. Whenever we encountered a structure with a built-in 
pointer, we changed that pointer to a standard 32-bit pointer type. We also 
changed an important part of the device driver, the device header. This 
structure defines the name of the driver, the type of device the driver 
supports, its capabilities, and pointers to major sections of internal device 
driver code. This has been a source of problems with the 16-bit device 
driver model. In the 16-bit design, the device header contains 16-bit offset 
pointers to the Initialization and Strategy sections of the device driver. The 
Initialization entry point is called when the device driver is loaded and the 
Strategy section is called for every other command sent to the driver. 
Because those pointers were only 16-bit pointers, the largest driver that 
could be written had to fit within a 64K-code segment. There was a 
workaround, though, by having the header point to an entry point in the 
first 64K segment. The first segment would then jump to a second code 


segment. Implementing this was quite tricky and resulted in some ugly 


code. Making these pointers 32-bit allows the driver to install an interrupt 


or timer handler anywhere in physical memory". 


This is important because OS/2 loads all 16-bit device drivers in low 
memory (less than 1MB). This memory is a precious commodity, and it’s 
easy to run out of space with several large multi-segment device drivers. 
Allowing the driver to be located anywhere in memory releases it from 
many historical limitations and helps free up lower memory. This means a 
major change to the system memory allocation routines, however, since 
the areas where device drivers are loaded must be permanently locked in 
memory and must be arranged as to prevent fragmentation. As part of 
our rewrite, we have specified that the OS/2 kernel must perform a post- 
boot compaction of device drivers as to avoid fragmentation. We also 


specified that the driver contains a special bit to override compaction. 


Another limitation that we addressed was the entry points for timer and 
interrupt handler routines. When a device driver needs to install an 
interrupt or timer handler, it calls a system function, passing the entry point 


of the interrupt or timer handler code. Because these pointers were 16-bit, 


the timer and interrupt handlers had to reside in the first code segment so 
the handler could be reached with a 16-bit pointer. Once in the interrupt 
handler, the handler code could call or jump into another segment, but this 
was also difficult to implement. Crossing segment boundaries is time 
consuming because the cache becomes invalidated and has to be 


reloaded each time a 64K boundary is crossed. 


Driver Loading 

For this rewrite, we have specified that OS/2 device drivers can be loaded 
after the system is booted and running. This requires a large change in the 
system loader and support code, but we feel this will be made easier by 
allowing the device drivers to be loaded anywhere in memory. When 
loading device drivers, the system keeps a list of installed device drivers in 
a chain of pointers. The chain pointer is initialized to the address of the 
first device driver's header. Each subsequent device driver header 
contains the address of the next device driver in the chain. The 16-bit 
device driver header uses an unsigned long (ULONG) for this pointer, so 
the system should be able to chain 16-bit and 32-bit device drivers without 


any extra logic in the chaining algorithm. 


When the driver is opened, the system will check a specific bit in the 
device driver’s header that identifies the driver as a new 32-bit driver. 
Once the determination has been made, the system can selectively send 
request packets that are formatted correctly for the model. A READ 
request packet, for example, contains the address of a data buffer in 
program space where data is to be stored. For the 16-bit model, those 
pointers will be passed as 16:16, for the 32-bit model, the pointers will be 
passed as linear addresses. The system will handle thunking 32-bit 
pointers to 16-bit, and 16-bit to 32-bit. By using this transparent thunking, 
current 16-bit drivers will continue to work normally while allowing the new 
32-bit model to be supported. This is also important because OS/2 
supports both 16-bit applications and 32-bit applications at the same time. 
It is possible, for example, for a 16-bit application to call a 32-bit driver, or 
a 32-bit application to call a 16-bit driver. Existing applications should 
continue to run unchanged, and to be able to utilize the new device driver 


model without a recompile’. 


Resource Allocation 

Device drivers allocate and use system hardware and software resources 
to perform operations. If the device uses DMA to transfer data, the device 
driver must reserve (or have available) a DMA channel it can use when it 
needs to transfer data. If the device uses interrupts, the driver must 
reserve that interrupt so it can handle the interrupt from the device. If the 
driver waited until the last possible moment to see if the resource was 
available, it would fail if a program tried to use the device and the resource 
was not available. This might be satisfactory for a printer, but not for a 


cardiac monitor or bank teller machine. 


Driver Information File 
The device driver determines the acceptable hardware configuration by 
referring to a driver information file, or DIF (see Figure 4.1. - Sample DIF 


File. 


; name of the driver 

DriverName] 

Samples 

; file name and location 

DriverLocation] 
c:\os2\drivers\sampledd.sys 

; locator program 

Locator] 

:\os2\locator\samploc.exe 

ASCII description 

Description] 

Sample base device driver 

; 16 for 16-bit model, 32 for flat model 
DriverModel] 

32 

; free form ASCII text 

Company] 

Our Company, Inc. 

7 version number nn.nn 

Version] 

«0G 

; hardware bus type and number 

Bus] 

PCIs0: PCL 21 

; interrupt levels IRQ:sharing (E=exclusive, S=shared) 
Interrupts] 

O23.E 7s Feiss Tek 

7 memory map (hex) address:length 
MemoryAddress] 

c0000::1000 cc000::1000 d4000::1000 d8000::1000 dc000::1000 
; Gdma channels 

DMA] 

7 ports (hex) address:length 

Ports] 

300::16 280::16 220::16 200::16 260::16 
; if adapter needs code downloaded to it 
Download] 

:\os2\drivers\init.cod::E0000 

specify driver power management support 
PowerManagement ] 

APM1.0 

ROM] 

C8000 


Q 


~ 





Q 


~ 








Figure 4.1. Sample DIF File 


Using the information in the DIF file and the current configuration of the 
hardware, the driver registers for the resources it requires by calling the 
system’s Resource Manager. The resource manager keeps track of the 


allocation and use of system resources. When a driver requests a 


resource, it calls the Resource Manager to request the use of that 
resource. The Resource Manager returns the status of that resource as 
AVAILABLE, NOT_AVAILABLE, or AVAILABLE_SHARED. Based on this 
information, the driver can determine what action to take. If the resource is 
available and the driver must absolutely have the resource, the driver calls 
the Resource Manager to reserve that resource exclusively. In some 
cases, the driver might allow sharing of that resource, but this is usually 
only safely done if the other driver or drivers sharing the resource are also 
aware that it will be shared. The driver uses the DIF file for a list of valid 
resources that the hardware supports. The DIF file also contains a list of 
substitute resources should the desired resource be unavailable. For 
instance, a particular device might request interrupt 5, but might also be 
able to use IRQ 4, IRQ 3, or IRQ 11. The DIF file contains a list of these 


resources in a hierarchy of desired resource allocation (see Figure 4.2). 


[Interrupts] 
5 43 11 


Figure 4.2. DIF File Interrupt Entry 


If the first resource in the category is unavailable, the driver will query the 


resource manager using the next supported resource until the request has 


been satisfied or all of the supported resources have been tried. The 


resources are organized in a hierarchical fashion, specifying the most 
optimal settings first followed by the least optimal. Using this method, the 
driver can determine the best configuration based on its intimate 
knowledge of the device. For instance, while configuring an interrupt, the 
driver could decide that based on the priority of the interrupt level it is 
granted, that the DMA channel should be an 8 bit DMA channel instead of 
a 16-bit DMA channel. The driver can make that decision based on its 


detailed knowledge of the device. 


After the driver has been loaded, the user can change the values of these 
parameters using the Configuration Manager application. This application 
displays the current configuration and settings for all devices, and 
wherever possible, allows these settings to be changed. Settings that 
cannot be changed are displayed in a lighter color to indicate that they 


cannot be adjusted manually. 


To make this concept work, existing 16-bit drivers should also include a 
DIF file and the associated code to request resources. It is not an absolute 


requirement, however. 


Recovery 

Each time the Configuration Manager is run, or a driver installed or 
changed, the current configuration is backed up to a file in case the 
current configuration causes the system to become unbootable or 
unstable. Each backup file is created with a different name using the 
current time and date. For example, a configuration file saved on October 
23, 1996 would be called something like C102396.DAT and stored in the 


Configuration Manager’s default directory. 


When the system is rebooted, a menu will appear for 10 seconds that will 
allow the user to reboot using a different configuration than the current 
configuration. If the user selects this option, a menu of the current saved 
configurations is listed. The user highlights the desired configuration and 
continues the boot progress. If the boot process succeeds, the system will 
ask the user if the new configuration should replace the existing 
configuration. This will allow the user to boot the system with several 
experimental configurations without losing the last saved good 
configuration. The system always keeps a copy of the original 


configuration used when the operating system was installed to allow a 


default configuration to be used in the event that the system is rendered 


unbootable. 


Device Locator 

Each device driver must supply a device locator program that verifies the 
presence of the particular device and verifies its configuration. The 
configuration manager uses this program to detect if the device is present, 
and to locate the device driver in the event that it needs to install the 
device driver. The locator program name and path are located in the 


driver’s DIF file. 


Configuration Manager 

The OS/2 configuration manager should run every ten to fifteen seconds 
to detect the installation of new hardware devices. It queries the current 
configuration and compares it against the last stored configuration to see if 
any hardware has been added. To determine the current configuration, the 
configuration manager runs a list of locators. A locator is a program written 
by the device driver writer that queries the particular device to see if it is 
present. In addition to running every 10 seconds, the configuration 
manager will also be run if it detects a PCMCIA card insertion event. 
During system boot, one of the first drivers that are loaded is the 
configuration manager itself. At that time, the configuration manager driver 
signs up to receive power management and PCMCIA events. If a PCMCIA 
card is inserted or removed, the configuration manager is called to 


determine the new configuration. 


The configuration manager will allow the user to enter settings for device 
drivers and hardware that do not participate in the new configuration 
architecture. Existing 16-bit device drivers may elect to supply a DIF file 
and the code to arbitrate resources with the configuration manager. For 
those drivers that can’t be modified, the configuration manager program 
will supply a manual input to allow resources for legacy devices and 
drivers to be reserved. If, for example, a certain device has a non-movable 
port address of 0x300, the user can reserve that port address using the 


resource manager. 


Dynamic Loading 

If the configuration manager detects that a new device has been installed, 
it looks in the \OS2\DRIVERS directory for a DIF file that matches the 
device. If it finds the DIF file, it calls the system device driver loader to 
load the device driver. If the device driver is loaded successfully, the 
locator associated with that device driver is added to the list of installed 
locators. The next time the configuration manager runs, the locator 


associated with that device will find the device already present. 


If the correct DIF file cannot be found, the system will ask the user to enter 


a floppy disk that contains the DIF file and driver associated with the 


device. The system copies that DIF file and driver to the system's hard 
disk, and restarts the configuration process. In some cases, such as drive 


letter reassignment, rebooting the system may be required. 


Dynamic Driver Binding 

In current versions of OS/2, the device driver code uses static linking. Run 
time libraries, supplied by IBM and other vendors are linked with the 
device driver at build time and become part of the driver executable code. 
Because these driver libraries were created by different companies, the 
names of the functions are different, as well as the number and name of 
the function parameters. We plan to solve this problem by supplying a 32- 
bit standard driver run time library that is dynamically linked at driver 
load time. The driver links with the import library of the run time DLL just 
like a normal application links with a DLL’s import library. The difference is 
that the driver gets its own copy of the run time library which becomes 
statically linked at driver load time, not at build time, resulting in much 
smaller driver executables. The driver library has the look and feel of a 
standard DLL, but a separate instance of the DLL is created for each 
driver. Unlike traditional DLLs, this DLL-like entity can be loaded at boot 
time and while the system is operating at ring 0. Updated library DLLs can 


be shipped via the normal update channels. This DLL could have been 


shipped as a standard library (LIB) file, but by using a DLL format, we can 
include debug symbol information and allow the library to be run and 
tested at ring 3. We can also insure that the current shipping library DLL is 
compatible with the current build of the operating system, and that the 


library is MP safe. 


Debugger Modifications 

One of the problems in developing OS/2 device drivers is the lack of good 
debugging tools. The current debugger is actually a replacement OS/2 
kernel. It is loaded in place of the standard OS/2 kernel file, OS2KRNL. It 
provides support for debug information to be displayed and input from a 
standard terminal on a serial COM port. The current debugger is barely 
adequate, and does not support the display and modification of data 
structures. Commands and functions are cryptic and difficult to 
understand. We don’t feel, however, that the base command set should be 
changed. In spite of its weaknesses, developers have learned to use the 
debugger successfully, and we don’t want them to learn yet another 
command set. Since the debugger can already display and modify 32-bit 


values, it should be able to be used “as is” with few actual modifications. 


Chapter 5. - Summary and Conclusions 


Conclusions 

It is worth reiterating here that the purpose of this effort was to flatten the 
existing base device driver model for OS/2. It would have been much 
easier to start from scratch with a brand new architecture and to ignore the 


support for the 16-bit model, but this was not an option. 


Since the drivers we used were written in C, the conversion process was 
much easier than we expected. All three drivers were converted with no 
major problems. The C header file conversion was also easy. The first 
step was to get the drivers to compile and link successfully using a 32-bit 
compiler. For the compiler, we selected IBM’s Visual Age C++ compiler for 
OS/2. Using a compiler that is supplied by IBM makes the most sense 
since IBM also supplies the OS/2 operating system. We did not convert or 
use any assembly language stubs or programs because we did not want 
to supply a model that used them. Today’s C and C++ compilers do a 
great job at optimization, and any small performance gains realized by 
writing in assembler are insignificant compared to the software 


maintenance and support costs associated with assembler programming. 


Recommended Steps 

During the conversion process, we identified several steps that were 
necessary for the conversion of existing device drivers, and have arranged 
those steps above in Chapter 4, in their suggested order of 
implementation. This list is not complete because it only reflects the 
structure and coding techniques of the drivers we converted. Other drivers 
may use different coding techniques, library calls, or private data types, so 
the list should be used only as a general guideline when converting 


existing drivers. 


Size 

We were concerned that converting the drivers from 16-bit to 32-bit would 
cause an increase in size. Indeed, as we expected, the executable size of 
the drivers increased by an average of 30% or more, in one case the size 
increased 40%. However, given the choice of having no drivers or drivers 


that are larger, the choice is obvious. 


Necessary Changes to OS/2 
During the conversion process, we identified several major changes that 
must be implemented in the OS/2 kernel and file system to allow our new 


drivers to operate. 


All devices are accessed via the OS/2 file system. The file system is 
the operating system’s interface to all devices and I/O. The current file 
system implementation is 16-bit. The file system must be modified to 
support 32-bit device drivers and their associated data. This means 
that the file system must support 32-bit pointers. The challenge here is 
that the file system should continue to support existing devices and 
device drivers while adding support for 32-bit drivers and devices. 
Request packets that are sent to a 16-bit device driver should have the 
appropriate 16-bit pointers, while request packets that are sent to 32- 
bit drivers should use 32-bit pointers. We recommend that the number 
of request packets allocated by the system be doubled to 512 16-bit 
packets and 512 32-bit packets. Since the system supplies the driver’s 
stack, the stack pointers should be adjusted according to the driver 
model. Any system functions that are available to the device driver 
should have 16-bit and 32-bit entry points, allowing both models to 
coexist. For example, a call to set the entry point of the driver’s 
interrupt or timer handler should accept a segment:offset for a 16-bit 
driver and a 0:32 flat address for a 32-bit device driver. The driver must 
maintain the ability to handle pointer conversions on behalf of 16-bit 


applications. It may be, in fact, easier to flatten the file system 


completely and then add back in the support for 16-bit applications and 
device drivers. This would have the theoretical effect of enhancing 
OS/2’s support for large files and disk volumes, as well as faster file 
caching and buffering. The new file system must support long file 


names and large files’®. 


The OS/2 device driver loader must be modified to allow 16-bit and 32- 
bit device drivers to be loaded. 32-bit drivers can be loaded anywhere 
in memory, while 16-bit drivers will continue to be loaded in low 
memory’’. The loader should not use the CONFIG.SYS file for loading 
device drivers, but should use the current configuration file to build a 
device tree while the system is booting up. The loader should support 
Dynamic Binding to allow the driver to be bound to an instance of the 


driver support library at load time. 


OS/2 must be modified to support file ring 0 file I/O services. This 
functionality is also required for the configuration manager to store the 


system configuration information. 


e OS/2 must be modified to use the lower bits of the 8254 Counter-Timer 
to provide better granularity for system timer ticks and device driver 


profiling. 


e OS/2 must supply a standard set of driver library functions that operate 
at ring 0 as well as ring 3. These libraries should export both 16-bit and 
32-bit functions, and should be able to allocate and de-allocate 
memory using 32-bit linear addresses. These library routines must be 


MP safe and use the PASCAL calling convention. 


e The system should be modified to supply what we call “auto thunking’. 
Auto thunking makes all the conversions from 16-bit pointers and 
stacks to 32-bit, and the reverse. A 16-bit device driver should always 
receive 16-bit pointers, while a 32-bit driver will always receive 32-bit 


pointers'®. 


e OS/2 must supply a GUl-based configuration utility capable of 


displaying and editing the configuration file. 


e Adevelopment kit must be supplied that contains accurate 
documentation on how to convert 16-bit device drivers, as well as the 
appropriate header files, make files, debugging kernel, and library 


support software. 


Conclusions 

It is our assessment that although this model will work, the device driver 
conversion effort is minimal when compared with the effort necessary to 
modify OS/2 to accommodate the new design. The biggest problem is that 
the underlying file system is still 16-bit, and flattening the file system is not 
a trivial task. We estimate that the file system alone could take one man- 
year or more of effort, and a lengthy additional period of integration testing 


with many different drivers and system configurations. 
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Appendix A — Listings 


// sample 8255 parallel port device driver for OS/2 


#include "drvlib.h" 
#include "digio.h" 


extern void STRATEGY (); /* name of strat rout. in drvstart*/ 
extern void TIMER_HANDLER(); /* timer handler in drvstart */ 


DEVICEHDR devhdr = { 











(void far *) OxFFFFFFFF, /* link #7, 
(DAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute word */ 
(OFF) STRATEGY, /* &strategy */ 
(OFF) 0, /* &IDC routine Hf 
"DIGIOS " /* name/#units */ 
‘i 
FPFUNCTION DevHlp=0; /* pointer to DevHlp entry point */ 
UCHAR opencount = 0; /* keeps track of open's */ 
USHORT savepid=0; /* save thread pid ey 
LHANDLE lock_seg_han; /* handle for locking appl. seg */ 
PHYSADDR appl_buffer=0; /* address of caller's buffer */ 
ERRCODE err=0; /* error return a 
ULONG ReadID=0L; /* current read pointer be 
USHORT num_rupts=0; /* count of interrupts */ 
USHORT temp_char; /* temp character for in-out */: 
void far *ptr; /* temp far pointer */ 
FARPOINTER appl_ptr=0; /* pointer to application buffer */ 
char input_char,output_char; /* temp character storage */ 
char input_mask; /* mask for input byte */ 


/* messages */ 





char CrL£[]= "\r\n"; 

char InitMessagel[] = " 8 bit Digital I/O "; 

char InitMessage2[] = " driver installed\r\n"; 

char FailMessage[] = " driver failed to install.\r\n"; 


/* common entry point for calls to Strategy routines */ 


int main(PREQPACKET rp) 

{ 
void far *ptr; 
PLINFOSEG liptr; /* pointer to global info seg */ 
int <i; 


switch (rp->RPcommand) 
{ 
case RPINIT: /* 0x00 */ 
/* init called by kernel in protected mode */ 
return Init (rp); 


case RPREAD: /* 0x04 */ 
rp->s.ReadWrite.count = 0; /* in case we fail */ 
input_char = inp(DIGIO_INPUT);/* get data ef 


if (PhysToVirt( (ULONG) rp->s.ReadWrite.buffer, 
1,0, &appl_ptr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (MoveBytes ((FARPOINTER) &input_char,appl_ptr,1)) 

return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
rp->s.ReadWrite.count = 1; /* one byte read */ 
return (RPDONE) ; 


case RPWRITE: /* 0x08 */ 
rp->s.ReadWrite.count = 0; 
if (PhysToVirt( (ULONG) rp->s.ReadWrite.buffer, 
1,0,&appl_ptr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes(appl_ptr, (FARPOINTER) &output_char,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
outp (DIGIO_OUTPUT, output_char); /* send byte */ 
rp->s.ReadWrite.count = 1; /* one byte written ef 
return (RPDONE) ; 


case RPOPEN: /* O0x0d open driver mf: 
/* get current process id */ 
if (GetDOSVar (2, &ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
/* get process info */ 


liptr = *((PLINFOSEG far *) ptr); 
/* if this device never opened, can be opened by anyone*/ 
if (opencount == 0) /* first time this dev opened */ 
opencount=1; /* bump open counter «xy 
savepid = liptr->pidCurrent; /* save current PID J 
else 
if (savepid != liptr->pidCurrent) /* another proc */ 
return (RPDONE | RPERR | ERROR_NOT_READY) ;/*err*/ 
++opencount; /* bump counter, same pid */ 





return (RPDONE) ; 


case RPCLOSE: /* Ox0e DosClose,ct1l-C, kill*/ 
/* get process info of caller */ 
if (GetDOSVar (2, &ptr) ) 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

/* get process info from os/2 */ 
liptr= *((PLINFOSEG far *) ptr); /* ptr to linfoseg */ 
/* 
make sure that process attempting to close this device 
is the one that originally opened it and the device was 
open in the first place. 


*/ 
if (savepid != liptr->pidCurrent || opencount == 0) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
—-opencount; /* close counts down open cntr*/ 
return (RPDONE) ; /* return 'done' status aif 
case RPIOCTL: /* 0x10 */ 
/* 


The function code in an IOCtl packet has the high bit set 
for the DIGIOS board. We return all others with the done 
bit set so we don't have to handle things like the 5-48 
code page IOCtl 
*/ 
if (rp->s.IOCtl.category != DIGIO_CAT)/* other IOCtls */ 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


switch (rp->s.IOCtl.function) 


case 0x01: /* write byte to digio port ce | 
/* verify caller owns this buffer area */ 
if (VerifyAccess ( 


SELECTOROF (rp->s.IOCtl.parameters), /* selector */ 
OFFSETOF (rp->s.I0OCtl.parameters), /* offset */ 
Ly /* 1 byte af 
0) ) /* read only * 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes (rp->s.IOCtl.parameters, 
(FARPOINTER) &output_char,1) ) 
return (RPDONE RPERR | ERROR_GEN_FAILURE) ; 
outp (DIGIO_OUTPUT, output_char) ; /*send to digio*/ 
return (RPDONE) ; 


case 0x02: /* read byte w/wait from port */ 
/* verify caller owns this buffer area */ 
if (VerifyAccess ( 


SELECTOROF (rp->s.10Ctl.buffer), /* selector */ 
OFFSETOF (rp->s.10Ctl.buffer), /* offset ay 
ie /* 1 bytes) */ 
0)) /* read only *% 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.10Ctl.buffer), /* selector af 
1, /* lock forever */ 
0, /* wait for seg loc*/ 
(PLHANDLE) &lock_seg_han) ) /* handle returned */ 


return (RPDONE RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes (rp->s.IOCtl.parameters, 
(FARPOINTER) &input_mask,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
/* wait for switch to be pressed */ 
ReadID = (ULONG) rp; /* block ID «fF 
if (Block (ReadID,-1L,0,é&err) ) 
if (err == 2) 
return (RPDONE RPERR 
| ERROR_CHAR_CALL_INTERRUPTED) ; 





/* move data to users buffer */ 
if (MoveBytes ((FARPOINTER) &input_char, 
rp->s.10Ctl.buffer,1)) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
/* unlock segment */ 
if (UnLockSeg(lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE); 
return (RPDONE); 





case 0x03: /* read byte immed digio port */ 
/* verify caller owns this buffer area */ 
if (VerifyAccess ( 





SELECTOROF (rp->s.10Ctl.buffer), /* selector +f 
OFFSETOF (rp->s.10Ctl.buffer), /* offset if 
4, /* 4 bytes */ 
0)) /* read only *f 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
input_char = inp(DIGIO_INPUT); /* get data ae 


if (MoveBytes ((FARPOINTER) &input_char, 
rp->s.10Ctl.buffer,1)) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
return (RPDONE) ; 
default: 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
} 


/* don't allow deinstall */ 
case RPDEINSTALL: /* 0x14 */ 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
/* all other commands are flagged as bad */ 
default: 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


timr_handler () 
{ 
if (ReadID != 0) 
{ 
/* read data from port */ 
input_char = inp(DIGIO_INPUT );/* get data */ 
if ((input_char && input_mask) !=0) 
{ 
Run (ReadID) ; 
ReadID=0L; 


} 
/* Device Initialization Routine */ 


int Init (PREQPACKET rp) 
{ 

/* store DevHlp entry point */ 

DevHlp = rp->s.Init.DevHlp; 

/* install timer handler */ 

if (SetTimer ((PFUNCTION) TIMER_HANDLER)) { 
/* if we failed, deinstall driver with cstds=0 */ 
DosPutMessage(1l, 8, devhdr.DHname) ; 
DosPutMessage(1,strlen(FailMessage) ,FailMessage) ; 
rp->s.InitExit.finalCS = (OFF) 0; 
rp->s.InitExit.finalDS = (OFF) 0; 
return (RPDONE RPERR | ERROR_GEN_FAILURE) ; 





} 
/* configure 8255 parallel chip */ 

outp (DIGIO_CONFIG, 0x91); 

/* output initialization message */ 

DosPutMessage(1, 2, CrbLf); 

DosPutMessage(1, 8, devhdr.DHname) ; 

DosPutMessage(1, strlen(InitMessagel), InitMessagel1) 
DosPutMessage(1l, strlen(InitMessage2), InitMessage2) 
/* send back our code and data end values to os/2 */ 
if (SegLimit (HIUSHORT((void far *) Init), 





’ 
’ 


&rp->s.InitExit.finalcs) || SegLimit (HIUSHORT((void far *) 
InitMessage2), &rp->s.InitExit.finalDS) ) 
Abort (); 


return (RPDONE) ; 


Figure A-1. OS/2 parallel device driver, 16-bit version. 


/* 


digio.h memory map for os/2 device driver 

%/ 

#define DIGIO_CAT 0x91 /* category for DosDevIOCtl */ 
#define DIGIO_BASE 0x2c0 /* board address igi 
#define DIGIO_OUTPUT DIGIO_BASE /* output port */ 
#define DIGIO_INPUT DIGIO_BASE+1 /* input port ay 
#define DIGIO_CONFIG DIGIO_BASE+3 /* initialization port ef 


Figure A-2. Parallel driver header file. 


// file drvlib.h 
// This header file contains definitions intended to go with 
// DRVLIB.LIB, a C-callable subroutine library. 
































// 

// This file is for OS/2 2.0 

typedef unsigned char UCHAR; 

typedef unsigned short USHORT; 

typedef unsigned short BOOLEAN; 

typedef unsigned long ULONG; 

typedef UCHAR near *PUCHAR; 

typedef UCHAR far *FPUCHAR; 

typedef USHORT near *PUSHORT; 

typedef USHORT far *FPUSHORT; 

typedef ULONG near *PULONG; 

typedef ULONG far *FPULONG; 

typedef char near *PCHAR; 

typedef short near *PSHORT; 

typedef long near *PLONG; 

typedef void near *POINTER; 

typedef POINTER near *PPOINTER; 

typedef void far *FARPOINTER; 

typedef FARPOINTER near *PFARPOINTER; 

typedef FARPOINTER far *FPFARPOINTER; 

typedef USHORT ERRCODE; // error code returned 
typedef ERRCODE far *PERRCODE; // pointer to an error code 
typedef UCHAR FLAG; // 8-bit flag 

typedef FLAG far *PFLAG; // pointer to 8-bit flag 
typedef USHORT SEL; // 16-bit selector 

typedef SEL near *PSEL; // pointer to a selector 
typedef SEL far *FPSEL; // far pointer to selector 
typedef USHORT SEG; // 16-bit segment 

typedef USHORT OFF; // 16-bit offset 

typedef ULONG LOFF; // 32-bit offset 

typedef USHORT PID; // Process ID 

typedef USHORT TID; // Thread ID 

typedef ULONG PHYSADDR; // 32-bit physical address 
typedef ULONG LINADDR; // 32-bit linear address 
typedef LINADDR far *PLINADDR; // pointer to 32 bit address 
typedef PLINADDR far *PPLINADDR; // pointer to linear address 
typedef PHYSADDR far *PPHYSADDR; // pointer to 32-bit phys addr 
typedef char near *PSTRING; // pointer to character string 
typedef char far *FPSTRING; // far pointer to string 
typedef USHORT SHANDLE; // short (16-bit) handle 
typedef SHANDLE far *PSHANDLE; // pointer to a short handle 
typedef ULONG LHANDLE; // long (32-bit) handle 








typedef 


LHANDLE far 


*PLHANDLE; 


// pointers to functions 


typedef 
typedef 
typedef 
typedef 


// macro 
define 
define 


define 


// Combi 


define 
define 
define 
define 
define 
define 


// the 
typedef 








struc 
USHOR 
OFF 
OFF 
UCHAR 
char 
ULONG 
DEVICE 
typedef 


define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 








int (pascal 
int (pascal 
int (pascal 
int (pascal 
s 

FALSE 0 
TRUE 1 


MAKEP (sel, 


define MAKEBIGOFFSETOF (p) 


ne l(ow) & 


LOBYTE (w) 
HIBYTE (w) 
LOUCHAR (w) 
HIUCHAR (w) 
LOUSHORT (1) 
HIUSHORT (1) 


driver devi 
struct Devi 


// pointer to a long handle 


near *PFUNCTION) (); 
near * near *PPFUNCTION) (); 
far *FPFUNCTION) (); 
far * near *PFPFUNCTION) (); 


define NP near pascal 


off) 


// far pointer from selector-offset 


( (void far *) MAKEULONG(off, sel) ) 


( (ULONG) 


// get selector or offset from far pointer 


define SELECTOROF (p) ( ((USHORT far *) &(p)) [1]) 
define OFFSETOF (p) ( ((USHORT far *) &(p)) [0]) 
// Combine l(ow) & h(igh) to form a 32 bit quantity. 
define MAKEULONG(1, h)  ((ULONG) (( (USHORT) (1) ) 

| ((ULONG) ((USHORT) (h))) << 16)) 
define MAKELONG(1, h) ( (LONG) MAKEULONG (1, h) ) 


(OFFSETOF (p))) 


h(igh) to form a 16 bit quantity. 


LOUC 
HIUC 
( (UC 


HAR (w) 
HAR (w) 


define MAKEUSHORT(1, h) (((USHORT) (1) ) | ((USHORT) (h)) << 8) 


define MAKESHORT(1, h) ( (SHORT) MAKEUSHORT (1, h)) 


// get high and low order parts of a 16 and 32 bit quantity 


HAR) (w) ) 


(((USHORT) (w) >> 8) & Oxff) 


( (US 
( (US 


ce header 
ceHdr 





t DeviceHdr far *DHnext;// 


T DHattribu 
DHstrateg 
DHidc; 
DHname [8] 
reserved[ 
bit_strip 

HDR; 


DAW_CHR 
DAW_IDC 
DAW_IBM 
DAW_SHR 
DAW_OPN 
DAW_LEVEL1 
DAW_LEVEL2 
DAW_LEVEL3 
DAW_GIO 
DAW_CLK 
DAW_NUL 





te; 
yr 


81; 


’ 


0x8000 
0x4000 
0x2000 
0x1000 
0x0800 
0x0080 
0x0100 
0x0180 
0x0040 
0x0008 
0x0004 


// 
// 
// 
// 


// 


// ariver device attributes word 


HORT) (1) ) 
HORT) (((ULONG) (1) >> 16) & Oxffff)) 


pointer to next header, or FFFF 
device attribute word 

offset of strategy routine 
offset of IDC routine 

dev name (char) or #units (blk) 


bit 0 DevIOctl12 


DEVICEHDR near *PDEVICEHDR; 


1l=char, O=block 

1=IDC available in this DD 
1=non-IBM block format 
1=supports shared device access 
1=open/close, removable media 
level 1 

level 2 DosDevIOCt1l2 

level 3 bit strip 


=generic IOCtl supported 
=CLOCK device 
=NUL device 











USHORT 
USHORT 
FARPOINTER 
FARPOINTER 
FARPOINTER 

} MESSAGETABLE; 


id; 
fill_in_item; 
iteml; 

item2; 
item_last; 


// OS/2 circular character queues 


define DAW_SCR 0x0002 // 1=STDOUT (screen) 
define DAW_KBD 0x0001 // 1=STDIN (keyboard) 
// capabilities bit strip 
define CBS_SHD 0x0001 // 1=shutdown/DevI0Ct12 
define CBS_HMEM 0x0002 // high memory map for adapters 
define CBS_PP 0x0004 // supports parallel ports 
define CBS_ADD 0x0010 // driver is an ADD 
define CBS_INIT 010020 // dariver receives InitComplete 
// SaveMessage structure 
typedef struct MessageTable 


index of next char to put out 
number of charactes in queue 


#define QUEUE_SIZE 512 // size of queues 
typedef struct CharQueue 
{ 
USHORT qsize; // number of bytes in queue 
USHORT qchrout; // 
USHORT qcount; Lh 
UCHAR qbuf [QUEUE_SIZE]; 


} CHARQUEUE; 
typedef CHARQUE 


UE near *PCHARQUEUE; 


// AttachDD inter device driver communication data area 
typedef struct AttachArea 


{ 
OFF 
SEG 
SEG 
OFF 


realOFF; 
realCs; 
realDS; 
protoOFF,; 
SEL protCs; 
SEL protDS; 
} ATTACHAREA; 


real-mode CS 
real-mode DS 
protect—mode 
protect—mode 
protect—mode 


typedef ATTACHAREA near *PATTACHAREA; 


// dariver reque 
typedef struct 
{ 


UCHAR RPlength; 





st packet 
ReqPacket 


offset of ide entry 


point 
of IDC entry point 
of IDC DD 

offset of entry pt 
CS of entry point 


DS of other DD 


request packet length 





UCHAR RPunit; // unit code for block DD only 
UCHAR RPcommand; // command code 
USHORT RPstatus; // status word 
UCHAR RPreserved[4]; // veserved bytes 
ULONG RPqlink; // queue linkage 
union 
{ // command-specific data 
UCHAR avail[19]; 
struct 
{ // init 
UCHAR units; // number of units 
FPFUNCTION DevH1p; // &DevHlp 
char far *args; // &args 
UCHAR drive; // drive # 
}Init; 


st 


ruct 
































UCHAR units; 
OFF finalcs; 
OFF finalDS; 
FARPOINTER BPBarray; 

} InitExit; 

struct 

{ 
UCHAR media; 
PHYSADDR buffer; 
USHORT count; 
ULONG startsector; 
USHORT reserved; 

} ReadWrite; 

struct 

{ 
UCHAR media; 
PHYSADDR buffer; 
USHORT count; 
ULONG startsector; 
USHORT reserved; 
CReadWrite; 

struct 
UCHAR subcode; 
ULONG reserved; 
Shutdown; 

struct 
USHORT sysfilenum; 
OpenClose; 

struct 
UCHAR category; 
UCHAR function; 
FARPOINTER parameters; 
FARPOINTER buffer; 
LOCtL? 

struct 
UCHAR char_returned; 
ReadNoWait; 

struct 
UCHAR media; 
UCHAR return_code; 
FARPOINTER prev_volume; 
MediaCheck; 

struct 
UCHAR media; 
FARPOINTER buffer; 
FARPOINTER BPBarray; 
UCHAR drive; 

} BuildBPB; 

struct 

{ 
UCHAR count; 
ULONG reserved; 

} Partitionable; 

struct 

{ 
ULONG units; 





// 
// 


// 
// 


same as input 
final offset, 
final offset, 
&BPB 


lst code segment 
lst data segment 


read, write, write w/verify 
media descriptor 

transfer address 
bytes/sectors 

starting sector# 


cached rd, wr, write w/verify 
media descriptor 

transfer address 
bytes/sectors 

starting sector# 


system shutdown 
sub request code 


open/close 
system file number 


roctl 
category code 
function code 
&parameters 
&buffer 


read, no wait 
char to return 


media check 

media descriptor 
see #defines 
&previous volume ID 


build BPB 

media descriptor 
1-sector buffer FAT 
&BPB array 

drive # 


query part. fixed disks 


# disks 


fixed disk LU map 
units supported 


ULONG reserved; 

} GetFixedMap; 

struct 

{ ef. 
UCHAR reserved[3]; 
FARPOINTER capstruct; // 
FARPOINTER volcharstruct; // 

} GetDriverCaps; 

} Ss; // 


} REQPACKET; 


typedef REQPACKET far *PREQPACKET; 
typedef PREQPACKET far *PPREQPACKET; 
typedef PREQPACKET QHEAD; TY: 
typedef QHEAD near *PQHEAD; 


// Global Info Seg 
typedef struct _GINFOSEG 
{ 

















ULONG time; 
ULONG msecs; 
UCHAR hour; 
UCHAR minutes; 
UCHAR seconds; 
UCHAR hundredths; 
USHORT timezone; 
USHORT cusecTimerInterval; 
UCHAR day; 
UCHAR month; 
USHORT year; 
UCHAR weekday; 
UCHAR uchMajorVersion; 
UCHAR uchMinorVersion; 
UCHAR chRevisionLetter; 
UCHAR sgCurrent; 
UCHAR sgMax; 
UCHAR cHugeShift; 
UCHAR fProtectModeOnly; 
USHORT pidForeground; 
UCHAR fDynamicSched; 
UCHAR csecMaxWait; 
USHORT cmsecMinSlice; 
USHORT cmsecMaxSlice; 
USHORT bootdrive; 
UCHAR amecRAS [32]; 
UCHAR csgWindowableVioMax; 
UCHAR csgPMMax; 

} GINFOSEG; 


typedef GINFOSEG far *PGINFOSEG; 


// local info seg 
typedef struct _LINFOSEG 
{ 








PID pidCurrent; 
PID pidParent; 
USHORT prtyCurrent; 
TID tidCurrent; 
USHORT sgCurrent; 
UCHAR rfProcStatus; 
UCHAR dummy 1; 
USHORT fForeground; 
UCHAR typeProcess; 
UCHAR dummy 2; 


get driver capabilities 


16:16 pointer to DCS 
16:16 pointer to VCS 


command info 


Queue Head is &ReqPacket 


SEL 
USHORT 
USHORT 
USHORT 
USHORT 
USHORT 
SEL 

} LINFOS 


selEnvironment; 


of 


fCmdLine; 


cbhDataSegment; 
cbStack; 
cbhHeap; 
hmod; 
selDS; 


EG; 


typedef LINFOSEG far *PLINFOSEG; 
typedef struct _REGSTACK 


{ 
USHORT 
USHORT 


USHORT 
USHORT 
USHORT 
USHORT 
USHORT 


usStruct; 
usFlags; 


us 


IRQ; 


usStackCLI; 
usStackSTI; 
usStackEOI; 
usNest; 

typedef REGSTACK near 


// page list struct 
typedef struct _PAGELIST 


PAGELI 


define 
define 
define 
define 


define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 


define 
define 
define 
define 








S14 


ULONG pl_Physaddr; 
ULONG pl_cb; 


// RPstatus bit values 


RPERR 0x8000 
RPDEV 0x4000 
RPBUSY 0x0200 
RPDONE 0x0100 


ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 
ERRO 


RPIN 
RPME 
RPBU 





// driver request codes 


LT. 
DIA_CHECK 
ILD_BPB 





RPREAD 


// 
// 


// 


stack usage structure 

set to 14 before using 

0x01 means that the interrupt proc 

enables interrupts. All others resvd 

IRQ of interrupt handler 

# of stack bytes with interrupts off 

# of stack bytes with interrupts on 

number of bytes needed after EOI 

max number of nested levels } REGSTACK; 


*PREGSTACK; 


0x00 
Ox01 
0x02 
0x04 


typedef PAGELIST far *PPAGELIST; 


error occurred, err in RPstatus 
error code defined by driver 
device is busy 

driver done with request packet 


// error codes returned in RPstatus 


R_WRITE_PROTECT 0x0000 
R_BAD_UNIT 0x0001 
R_NOT_READY 0x0002 
R_BAD_COMMAND 0x0003 
R_CRC 0x0004 
R_BAD_LENGTH 0x0005 
R_SEEK 0x0006 
R_NOT_DOS_DISK 0x0007 
R_SECTOR_NOT_FOUND 0x0008 
R_OUT_OF_PAPER 0x0009 
R_WRITE_FAULT Ox000A 
R_READ_FAULT 0x000B 
R_GEN_FAILURE 0x000C 
R_DISK_CHANGE 0x000D 
R_WRONG_DISK Ox000F 
R_UNCERTAIN_MEDIA 0x0010 
R_CHAR_CALL_INTERRUPTED 0x0011 
R_NO_MONITOR_SUPPORT 0x0012 
R_INVALID_PARAMETER 0x0013 
R_DEVICE_IN_USE 0x0014 


B=block, C=character 


// BC 
// B 
// B 


define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 
define 


define 
define 


define 
define 
define 
define 
define 
define 
define 








// defines for 1 








// check for monitor call 
define MON_OPEN_STATUS 
define MON_CLOSE_STATUS 


// media descriptor byte 
define MDB _REMOVABLE 

define MDB_EIGHT_SECTORS 
define MDB_DOUBLE_SIDED 


MC_MEDIA_CHANGED 
MC_MEDIA_UNSURE 


EVENT_SM_MOUSE 
EVENT_CTRLBRK 
EVENT_CTRLC 
EVENT_CTRLNUMLK 
EVENT_CTRLPRTSC 
EVENT_SHFTPRTSC 
EVENT_SM_KBD 


RPREAD_NO_WAIT 0x05 
RPINPUT_STATUS 0x06 
RPINPUT_FLUSH 0x07 
RPWRITE 0x08 
RPWRITE_VERIFY 0x09 
RPOUTPUT_STATUS 0x0a 
RPOUTPUT_FLUSH 0x0b 
RPOPEN Ox0d 
RPCLOSE Ox0e 
RPREMOVABLE Ox0f 
RPIOCTL 0x10 
RPRESET Ox1l 
RPGET_DRIVE_MAP 0x12 
RPSET_DRIVE_MAP 0x13 
RPDEINSTALL 0x14 
RPPARTITIONABLE 0x16 
RPGET_FIXED_MAP 0x17 
RPSHUTDOWN Oxlc 
RPGET_DRIVER_CAPS 0xld 


in DosOpen/DosClose 
// open from DosMonOpen 
// close from DosMonClose 


0x08 
0x08 


0x04 
0x02 
0x01 


// return codes from MediaCheck 
define MC_MEDIA_UNCHANGED 0x01 


OxFF 
0x00 


// event numbers for SendEvent 


0x00 
0x01 
0x02 
0x03 
0x04 
0x05 
0x06 


-X movedata function 











// 
// 
// 


1=removable 


1=8 sectors per track 
1=double-sided media 


session 
control break 
control C 
control num lock 
control 
shift printscreen 


switch via mouse 


printscreen 


session switch hot key 


define MOVE_PHYSTOPHYS 0 // move phys to phys memory 
define MOVE_PHYSTOVIRT iG // move phys to virt memory 
define MOVE_VIRTTOPHYS 2 // move virt to phys memory 
define MOVE_VIRTTOVIRT ft // move virt to virt memory 
// Micro Channel specific 

int NP GetLIDEntry (USHORT,USHORT, USHORT, FPUSHORT) ; 

int NP FreeLIDEntry (USHORT) ; 

int NP ABIOSCall (USHORT,USHORT, FARPOINTER) ; 

int NP ABIOSComm (USHORT,FARPOINTER) ; 

int NP GetDeviceBlock (USHORT,FARPOINTER) ; 


// special routines 


NP 
NP 
NP 
NP 
NP 


void 
void 
void 
void 
int 


INT3 (void); 
Enable (void); 
Disable (void) ; 
Abort (void); 


SegLimit 


(SEL,OFF far *); 


SchedClockAddr (PFARPOINTER) 
AttachDD (PSTRING, PATTACHAREA) ; 


P MoveBytes (FARPOINTER, FARPOINTER, FLAG) ; 
P MoveData (FARPOINTER, FARPOINTER, USHORT, USHORT) ; 


P GetDOSVar (USHORT, FPFARPOINTER) ; 


~~ 





int N 

int N 

// system services and misc. 
int N 

int NP SendEvent (USHORT,USHORT) ; 
void NP 

int NP 

int NP 

int NP SaveMessage(FPSTRING) ; 
int NP ProtToReal (void); 

int NP RealToProt (void); 

int NP 








InternalError (PSTRING, USHORT) ; 





SetROMVector (USHORT, PFUNCTION, PFUNCTION, FARPOINTER) ; 


// process mgmt 


void 
void 
int 
void 
void 


N 
N 
N 
N 
N 
int N 


// memory management 


in 
in 
in 
in 
in 


att tte 


222242 


Yield (void); 
TCYield (void); 


Block (ULONG, ULONG, USHORT, FARPOINTER) ; 


Run  (ULONG) ; 


DevDone (PREQPACKET) ; 
VideoPause (USHORT) ; 


AllocPhys (ULONG, 


FreePhys (PHYSADDR) ; 


USHORT 


VerifyAccess (SEL, OFF,U 


LockSeg (SEL, US 
UnLockSeg (LHANDLE) ; 





// address conversion 


in 
in 
in 
in 
in 
in 


22222424 


atctctotacadec 


// request packet queue stuff 


int 
void 
void 
void 


22222424 


// driver semaphores 





// circular character 


void N 
void N 
int N 


// interrupt stuff 


int N 
int N 
int N 
void N 
void N 
int N 


Pp 


Pp 


Pp 


Pp 


Pp 


Pp 


Pp 





HORT, U 


P AllocGDTSelector (USHORT 
PhysToGDTSelector 


(PHYSA 


VirtToPhys (FARPOINTER, 
PhysToUVirt (PHYSADDR,U 
PhysToVirt (PHYSADDR, US 


UnPhysToVirt (void); 





td 
D 
Pp 
S 
H 





SemHandle (LHANDLE, FLAG, 


SemRequest (LHAND 


SemClear (LHANDLE) ; 


queues 


QueueInit (PCHARQUEUE) ; 
QueueFlush (PCHARQUEUE) ; 
QueueWrite (PCHARQUEUE, UCHAR) ; 
QueueRead (PCHARQUEUE, FPUCHAR) ; 











PPHYSADDR) ; 


HORT, USHORT) ; 
HORT, PLHANDLE) ; 


FARPOINTER) ; 

DR, USHORT, SEL, PERRCODE) ; 
PHYSADDR) ; 

HORT, USHORT, FPFARPOINTER) ; 
ORT, USHORT, FARPOINTER) ; 








P AllocRegqPacket (USHORT, PPREQPACKET) ; 
P FreeReqPacket (PREQPACKET) ; 

P PushReqPacket (PQHEAD, PREQPACKET) ; 
P SortReqPacket (PQHEAD, PREQPACKET) ; 
P PullReqPacket (PQHEAD, PPREQPACKET) ; 
P PullParticular (PQHEAD, PREQPACKET) ; 





PLHANDLE) ; 


LE, ULONG, PERRCODE) ; 


SetIRQ (USHORT,PFUNCTION, USHORT) ; 


UnSetIRQ (USHORT) 
EOI (USHORT) ; 


7 


ClaimInterrupt (void) ; 
RefuselInterrupt (void) ; 
RegisterStackUsage (PREGSTACK) ; 


// timer stuff 






























































int NP SetTimer (PFUNCTION) ; 

int NP ResetTimer (PFUNCTION) ; 

int NP TickCount (PFUNCTION, USHORT) ; 

// device monitors 

int NP MonCreate (PSHANDLE, FARPOINTER, FARPOINTER, PERRCODE) ; 
int NP Register (SHANDLE, USHORT, PID, FARPOINTER, OFF, PERRCODE) ; 
int NP MonWrite (SHANDLE, POINTER, USHORT, USHORT, ULONG, PERRCODE) ; 
int NP MonFlush (SHANDLE, PERRCODE) ; 

int NP DeRegister (SHANDLE, PID, PERRCODE) ; 

// 2.0 specfic 

int NP RegisterPDD (FPUCHAR, FPFUNCTION) ; 

int NP RegisterBeep (FPFUNCTION) ; 

int NP Beep (USHORT,USHORT) ; 

int NP FreeGDTSelector (USHORT) ; 

int NP PhysToGDTSel (PHYSADDR, ULONG, SEL, USHORT, FPUSHORT) ; 

int NP VMLock (LINADDR, ULONG, LINADDR, LINADDR, ULONG, FPULONG) ; 
int NP VMUnlock (LHANDLE) ; 

int NP VMAlloc(PLINADDR, ULONG, ULONG, PLINADDR) ; 

int NP VMFree(PHYSADDR) ; 

int NP VMProcessToGlobal (LINADDR, ULONG, ULONG, PLINADDR) ; 

int NP VMGlobalToProcess (LINADDR, ULONG, ULONG, PLINADDR) ; 

int NP VirtToLin(FARPOINTER, PLINADDR) ; 

int NP LinToGDTSelector (SEL, LINADDR, ULONG) ; 

int NP GetDescInfo (SEL, FPUSHORT, FPULONG, FPULONG) ; 

int NP LinToPageList (LINADDR, ULONG, LINADDR, FPULONG) ; 

int NP PageListToLin(ULONG, LINADDR, PLINADDR) ; 

int NP PageListToGDTSelector (SEL, ULONG, LINADDR, USHORT, FPUSHORT) ; 
int NP RegisterTmrDD (FPFUNCTION, FPFARPOINTER, FPFARPOINTER) ; 
int NP AllocateCtxHook (OFF, ULONG, PLHANDLE) ; 

int NP FreeCtxHook (LHANDLE) ; 

int NP ArmCtxHook (ULONG, LHANDLE, ULONG) ; 

int NP VMSetMem(LINADDR, ULONG, ULONG) ; 

int NP OpenEventSem(LHANDLE) ; 

int NP CloseEventSem(LHANDLE) ; 

int NP PostEventSem(LHANDLE) ; 

int NP ResetEventSem(LHANDLE, FPULONG) ; 

int NP DynamicAPI (FARPOINTER, USHORT, USHORT, FPUSHORT) ; 

// these are the only API's available to the driver at Init time 
define APIENTRY far pascal 


HORT APIENTRY DosBeep (USHORT, USHORT) ; 

HORT APIENTRY DosCaseMap (USHORT, FARPOINTER, FARPOINTER) ; 

HORT APIENTRY DosChgFilePtr (SHANDLE, long, USHORT, FARPOINTER) ; 
[ APIENTRY DosClose (SHANDLE) ; 
HORT APIENTRY DosDelete (FARPOINTER, ULONG) ; 

HORT APIENTRY DosDevConfig (FARPOINTER, USHORT, USHORT) ; 
HORT APIENTRY DosDevIOCtl (FARPOINTER, FARPOINTER, USHORT, 
USHORT, USHORT) ; 
USHORT APIENTRY DosFindClose (SHANDLE) ; 
USHORT APIENTRY DosFindFirst (FARPOINTER, FARPOINTER, USHORT, 
FARPOINTER, USHORT, FARPOINTER, ULONG) ; 
USHORT APIENTRY DosFindNext (SHANDLE, FARPOINTER, USHORT, 
FARPOINTER) ; 
USHORT APIENTRY DosGetEnv (FARPOINTER, FARPOINTER) ; 
USHORT APIENTRY DosGetMessage (FARPOINTER, USHORT, FARPOINTER, 
USHORT, USHORT, FARPOINTER, FARPOINTER) ; 
USHORT APIENTRY DosOpen (FARPOINTER, FARPOINTER, FARPOINTER, 
ULONG, USHORT, USHORT, USHORT, ULONG) ; 


C 
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DosPutMessage (SHANDLE, USHORT, FARPOINTER) 
DosQCurDir (USHORT, FARPOINTER, FARPOINTER) 
DosQCurDisk (FARPOINTER, FARPOINTER) ; 

DosQFileInfo (SHANDLE, USHORT, FARPOINTER, USHORT) ; 
DosQFileMode (FARPOINTER, FARPOINTER, ULONG) ; 

DosRead (SHANDLE, FARPOINTER, USHORT, FARPOINTER) ; 
DosWrite (SHANDLE, FARPOINTER, USHORT, FARPOINTER) ; 


’ 
’ 


Figure A-3. Driver library header file, 16-bit. 


This header file contains definitions intended to go along with 


a C-callable subroutine library. 











USHORT APIENTRY 

USHORT APIENTRY 

USHORT APIENTRY 

USHORT APIENTRY 

USHORT APIENTRY 

USHORT APIENTRY 

USHORT APIENTRY 

// end of DRVLIB.H 

if file drvlib32.h 32-bit version 
// 

ak DRVLIB.LIB, 

// 

// This file 1s fer 08/2. 2. 
typedef unsigned char UCHAR; 
typedef unsigned short USHORT; 
typedef unsigned short BOOLEAN; 
typedef unsigned long ULONG; 
typedef UCHAR *PUCHAR; 
typedef USHORT *PUSHORT; 
typedef ULONG *PULONG; 
typedef char *PCHAR; 
typedef short *PSHORT; 
typedef long *PLONG; 
typedef void *PVOID; 
typedef PVOID *PPVOID; 
typedef USHORT ERRCODE; 
typedef ERRCODE *PERRCODE; 
typedef UCHAR FLAG; 
typedef FLAG *PFLAG; 
typedef USHORT SEL; 
typedef SEL *PSEL; 
typedef USHORT OFFSET; 
typedef USHORT SEG; 
typedef USHORT PID; 
typedef USHORT TID; 
typedef ULONG PHYSADDR; 
typedef ULONG LINADDR; 
typedef LINADDR *PLINADDR; 
typedef PLINADDR *PPLINADDR; 
typedef PHYSADDR *PPHYSADDR; 
typedef char *PSTRING; 
typedef USHORT SHANDLE; 
typedef SHANDLE *PSHANDLE; 
typedef ULONG LHANDLE; 
typedef LHANDLE HSPINLOCK; 
typedef LHANDLE *PLHANDLE; 
typedef HSPINLOCK *PHSPINLOCK; 
// pointers to functions 

typedef int ( *PFUNCTION) 
typedef int ( * *PPFUNCTION) (); 


QO; 


returned 
an error code 


error code 
pointer to 
8-bit flag 
pointer to 8-bit flag 

16-bit selector 

pointer to a selector 

16-bit offset 

16-bit segment 

Process ID 

Thread ID 

32-bit physical address 

32-bit li address 

pointer to 32 bit li address 
pointer to li address pointer 
pointer to 32-bit physical address 
pointer to character string 


short (16-bit) handle 
pointer to a short handle 
long (32-bit) handle 


spinlock handle 
pointer to a long handle 
pointer to spinlock handle 


// macros 


define FALSE 
define TRUE 


0 




















// pointer from selector-offset 

define MAKEP (sel, off) ( (void *) MAKEULONG(off, sel) ) 
// get selector or offset from pointer 

define SELECTOROF (p) ( ((USHORT *) &(p)) [1]) 

define OFFSETOF (p) ( ((USHORT *) &(p)) [0]) 

// Combine l(ow) & h(igh) to form a 32 bit quantity. 

define MAKEULONG (1, h) ( (ULONG) (((USHORT) (1) ) | ( (ULONG) ( (USHORT) (h) ) 
define MAKELONG(1, h) ( (LONG) MAKEULONG (1, h) ) 

define MAKEBIGPFUNCTIONSETOF(p) ((ULONG) (PFUNCTIONSETOF (p))) 
// Combine l(ow) & h(igh) to form a 16 bit quantity. 

define MAKEUSHORT(1, h) (((USHORT) (1) ) | ((USHORT) (h)) << 8) 
define MAKESHORT (1, h) ( (SHORT) MAKEUSHORT (1, h)) 


// get high and low order parts of a 16 and 32 bit quantity 


define LOBYTE (w) LOUCHAR (w) 

define HIBYTE(w) HIUCHAR (w) 

define LOUCHAR(w) ( (UCHAR) (w) ) 

define HIUCHAR(w) (((USHORT) (w) >> 8) & Oxff) 

define LOUSHORT (1) ((USHORT) (1) ) 

define HIUSHORT (1) ((USHORT) (((ULONG) (1) >> 16) & Oxffff)) 
// the driver device header 


typedef struct DeviceHdr 
{ 


struct DeviceHdr *DHnext; 
USHORT DHattribute; 
PFUNCTION DHstrategy; 
PFUNCTION DHidc; 
UCHAR DHname [8]; 
char reserved[8]; 
ULONG bit_strip; 
} DEVICEHDR; 
typedef DEVICEHDR *PDEVICEHDR; 
// ariver device attributes word 
define DAW_CHR 0x8000 
define DAW_IDC 0x4000 
define DAW_IBM 0x2000 
define DAW_SHR 0x1000 
define DAW_OPN 0x0800 
define DAW_LEVEL1 0x0080 
define DAW_LEVEL2 0x0100 
define DAW_LEVEL3 0x0180 
define DAW_GIO 0x0040 
define DAW_CLK 0x0008 
define DAW_NUL 0x0004 
define DAW_SCR 0x0002 
define DAW_KBD 0x0001 











// pointer to next header, 


or FFFF 
device attribute word 
offset of strategy routine 
offset of IDC routine 
dev name (char) or #units (blk) 


bit 0 DevIOCt12, bit 1 32 bit addr 


l=char, O=block 

1=IDC available in this DD 
1=non-IBM block format 
1l=supports shared device access 
l=open/close, or removable media 
level 1 

level 2 DosDevIOCt12 

level 3 bit strip 

l=generic IOCtl supported 
L=CLOCK device 

1=NUL device 

1=STDOUT (screen) 

1=STDIN (keyboard) 





<< 16)) 


// capabilities bit strip 


#define CBS_SHD 0x0001 
#define CBS_HMEM 0x0002 
#define CBS_PP 0x0004 
#define CBS_ADD 0x0008 
#define CBS_INIT 0x0010 


// SaveMessage structure 


typedef struct MessageTable 
{ 
USHORT 
USHORT 
PVOID 


id; 
fill_in_item; 
iteml; 
PVOID item2; 
PVOID item_last; 
} MESSAGETABLE; 


// OS/2 circular character queues 


#define QUEUE_SIZE 512 
typedef struct CharQueue 
{ 


USHORT qsize; 

USHORT qchrout; 

USHORT qcount; 

UCHAR qbuf [QUEUE_SIZE]; 


} CHARQUEUE; 


typedef CHARQUEUE *PCHARQUEUE; 


// 


// 
// 
// 


// PortIO structure for SMP systems 


typedef struct _PORTIO_STRUCT 
{ 


ULONG port; 
ULONG data; 
ULONG flags; 


} PORTIO_STRUCT; 








typedef PORTIO_STRUCT *PPORTIO_STRUCT; 
// defines for PortIOStruct flags 
#define PORTIO_READ_BYTE 0x00 

#define PORTIO_READ_WORD 0x01 

#define PORTIO_READ_DWORD 0x02 

#define PORTIO_WRITE_BYTE 0x03 

#define PORTIO_WRITE_WORD 0x04 

#define PORTIO_WRITE_DWORD 0x05 
#define PORTIO_FLAG_MASK 0x07 


// structures and equates for APM 


// APM IDC return codes 


#define 
#define 
#define 
#define 
#define 


APMIDC_Register 
APMIDC_DeRegister 
APMIDC_SendEvent 
APMIDC_QueryStatus 
APMIDC_QueryInfo 


// APM IDC return codes 


0x00 
0x01 
0x02 
0x03 
0x04 


1=shutdown/DevIOCct12 

hign memory map for adapters 
supports parallel ports 
driver is an ADD 

driver receives InitComplete 


size of queues 


number of bytes in queue 
index of next char to put out 
number of charactes in queue 


// port to read/write 
// data to write or returned from read 
// flags defined below 


define APMIDC_InvalidFunction 0x00 


define APMIDC_InvalidHandle 0x01 
define APMIDC_InvalidDevice 0x02 
define APMIDC_InvalidEvent 0x03 
define APMIDC_InvalidOther 0x04 
define APMIDC_InterfaceBusy 0x05 
define APMIDC_RequestRejected 0x06 
define APMIDC_InvalidMask 0x07 


// APM Notification Mask Definitions 


define APMMASK_EnableAPM 0x08 
define APMMASK_ DisableAPM 0x10 
define APMMASK_BIOS_Defaults 0x20 
define APMMASK_ SetPowerState 0x40 
define APMMASK_ BatteryLow 0x80 
define APMMASK_NormalResume 0x100 


define APMMASK_CriticalResume 0x200 
define APMMASK_AllAppNotifyBits 0x3f8 


// APM Event Identification 


define APMEVENT_EnableAPM 0x03 
define APMEVENT_DisableAPM 0x04 
define APMEVENT_BIOS_Defauts 0x05 
define APMEVENT_SetPowerState 0x06 
define APMEVENT_BatteryLow 0x07 
define APMEVENT_NormalResume 0x08 


define APMEVENT_CriticalResume 0x09 
// Notify defines 


define APMSTATE_READY 0x00 
define APMSTATE_STANDBY 0x01 
define APMSTATE_SUSPEND 0x02 
define APMSTATE_PFUNCTION 0x03 








// APM IDC Structures 


typedef struct _APMIDC_REGISTER_PKT 
{ 





USHORT RegFunction; 

USHORT ReghClient; 

USHORT RegEventHandleroOff; 
USHORT RegEventHandlerSel; 
ULONG RegNotifyMask; 
USHORT RegClientDSs; 

USHORT RegDevicelID; 








} APMIDC_REGISTER_PKT; 


typedef struct _APMIDC_NOTIFY_PKT 
{ 





USHORT NotifyFunction; 
USHORT SubID; 

USHORT Reserved; 
USHORT DevID; 

USHORT PwrState; 





} APMIDC_NOTIFY_PKT; 


typedef struct _APMIDC_DEREGISTER_PKT 
{ 


USHORT 
USHORT 


DregFunction; 
DreghClient; 


} APMIDC_DEREGISTER_PKT; 


typedef struct _APMIDC_SENDEVENT_PKT 
{ 


USHORT SendevFunction; 
USHORT SendevSubID; 
USHORT SendevReserved; 
USHORT SendevDevID; 
USHORT SendevPwrState; 





} APMIDC_SENDEVENT_PKT; 


typedef struct _APMIDC_QSTATUS_PKT 
{ 


USHORT QstatFunction; 
USHORT QstatParmLength; 
USHORT QstatFlags; 

UCHAR QstatACStatus; 

UCHAR QstateBatteryStatus; 
UCHAR QstateBatteryLife; 


} APMIDC_QSTATUS_PKT; 


typedef struct _APMIDC_QINFO_PKT 
{ 





USHORT QinfoFunction; 
USHORT QinfoParmLength; 
USHORT QinfoBIOSFlags; 
UCHAR QinfoBIOSMajor; 
UCHAR QinfoBIOSMinor; 
UCHAR QinfoDDMajor; 
UCHAR QinfoDDMinor; 
} APMIDC_QINFO_PKT; 
// AttachDD inter device driver communication data area 





typedef struct AttachArea 
{ 


PFUNCTION realPFUNCTION; // veal-mode offset of ide entry 


point 

SEG realCS; // veal-mode CS of IDC entry point 

SEG realDS; // creal-mode DS of IDC DD 

PFUNCTION protPFUNCTION; // protect-mode offset of entry 
point 

SEL protCs; // protect-mode CS of entry point 

SEL protDS; // protect-mode DS of other DD 


} ATTACHAREA; 
typedef ATTACHAREA *PATTACHAREA; 
// driver request packet 


typedef struct ReqPacket 
{ 


UCHAR RPlength; // request packet length 

UCHAR  RPunit; // unit code for block DD only 
UCHAR RPcommand; // command code 

USHORT RPstatus; // status word 

UCHAR RPreserved[4]; // veserved bytes 

ULONG RPqlink; // queue linkage 


union { // command-specific data 
UCHAR avail[19]; 


struct // init 
UCHAR units; // number of units 
PFUNCTION DevHlp; // &DevH1p 
char *args; // &args 
UCHAR drive; // drive # 
}Init; 
struct 
UCHAR unite; // same as input 
PFUNCTION finalcs; // final offset, lst code segment 
PFUNCTION finalDs; // final offset, lst data segment 
PVOID BPBarray; // &BPB 


} InitExit; 


struct // vead, write, write w/verify 
UCHAR media; // media descriptor 
PHYSADDR buffer; // transfer address 
USHORT count; // bytes/sectors 
ULONG startsector; // starting sector# 
USHORT reserved; 


} ReadWrite; 


struct // cached read, write, write w/verify 
UCHAR media; // media descriptor 
PHYSADDR buffer; // transfer address 
USHORT count; // bytes/sectors 
ULONG startsector; // starting sector# 
USHORT reserved; 


} CReadWrite; 











struct // system shutdown 
UCHAR subcode; // sub request code 
ULONG reserved; 


} Shutdown; 


struct { // open/close 
USHORT sysfilenum; // system file number 
} OpenClose; 











struct { fv TOseL 
UCHAR category; // category code 
UCHAR function; // function code 
PVOID parameters; // &parameters 
PVOID buffer; // &buffer 
} -<LOCEL; 

struct { // vead, no wait 
UCHAR char_returned; // char to return 


} ReadNoWait; 


struct { // media check 
UCHAR media; // media descriptor 
UCHAR return_code; // see #defines 
PVOID prev_volume; // &previous volume ID 


} MediaCheck; 





struct { // build BPB 
UCHAR media; // media descriptor 
PVOID buffer; // 1-sector buffer FAT 
PVOID BPBarray; // &BPB array 
UCHAR drive; // drive # 


} BuildBPB; 


struct { 
UCHAR count; 
ULONG reserved; 


} Partitionable; 


struct { 
ULONG units; 
ULONG reserved; 


} GetFixedMap; 


struct { 

UCHAR reserved[3]; 
PVOID capstruct; 

PVOID volcharstruct; 

} GetDriverCaps; 





} Ss; 
} REQPACKET; 


typedef REQPACKET *PREQPACKET; 
typedef PREQPACKET *PPREQPACKET; 
typedef PREQPACKET QHEAD; 

typedef QHEAD *PQHEAD; 


// Global Info Seg 


typedef struct _GINFOSEG 
{ 














ULONG time; 

ULONG msecs; 

UCHAR hour; 

UCHAR minutes; 

UCHAR seconds; 

UCHAR hundredths; 
USHORT timezone; 

USHORT cusecTimerInterval; 
UCHAR day; 

UCHAR month; 

USHORT year; 

UCHAR weekday; 

UCHAR uchMajorVersion; 
UCHAR uchMinorVersion; 
UCHAR chRevisionLetter; 
UCHAR sgCurrent; 

UCHAR sgMax; 

UCHAR cHugeShift; 

UCHAR fProtectModeOnly; 
USHORT pidForeground; 
UCHAR fDynamicSched; 
UCHAR csecMaxWait; 
USHORT cmsecMinSlice; 
USHORT cmsecMaxSlice; 
USHORT bootdrive; 

UCHAR amecRAS [32]; 
UCHAR csgWindowableVioMax; 
UCHAR csgPMMax; 


} GINFOSEG; 
typedef GINFOSEG *PGINFOSEG; 
// local info seg 


typedef struct _LINFOSEG 


// query partitionalble fixed disks 
// # disks 


// fixed disk LU map 
// units supported 


// get driver capabilities 


// 16:16 pointer to DCS 
// 16:16 pointer to VCS 


// command info 


// Queue Head is &RegPacket 


time in seconds 
milliseconds 
hours 

minutes 

seconds 
hundredths 
minutes from UTC 
timter interval, 
day of month 
month, 1-12 

year 

day of week, O0=Sunday, 
major version number 
minor version number 
rev level 

current foreground session 

max number of sessions 

shift count for huge elements 
protect mode only 

pid of last process in foreground 
dynamic variation flag 

max wait in seconds 

min timeslice in milliseconds 

max timeslice in milliseconds 
boot drive (0=a, 1=b...) 

system trace major code flag bits 
max number of VIO sessions 

max number of PM sessions 


-0001 secs 


1=Monday... 

















PID pidCurrent; // current process id 
PID pidParent; // process id of parent 
USHORT prtyCurrent; // priroty of current thread 
TID tidCurrent; // thread id of current thread 
USHORT sgCurrent; // current session id 
UCHAR rfProcStatus; // process status 
UCHAR dummy 1; // veserved 
USHORT fForeground; // current process is in foreground 
UCHAR typeProcess; // process type 
UCHAR dummy 2; // veserved 
SEL selEnvironment; // selector of environment 
USHORT offCmdLine; // command line offset 
USHORT cbDataSegment; // length of data segment 
USHORT cbStack; // stack size 
USHORT chbHeap; // heap size 
USHORT hmod; // module handle of application 
SEL selDS; // data segment handle of application 
} LINFOSEG; 
typedef LINFOSEG *PLINFOSEG; 
typedef struct _REGSTACK { // stack usgae structure 
USHORT usStruct; // set to 14 before using 
USHORT usFlags; // 0x01 means that the interrupt proc 
// enables interrupts. All others resvd 
USHORT usIRQ; // IRQ of interrupt handler 
USHORT usStackCLI; // # of stack bytes with interrupts off 
USHORT usStackSTI; // # of stack bytes with interrupts on 
USHORT usStackEOI; // number of bytes needed after EOI 
USHORT usNest; // max number of nested levels 
} REGSTACK; 
typedef REGSTACK *PREGSTACK; 
// page list struct 
typedef struct _PAGELIST 
{ 
ULONG pl_Physaddr; 
ULONG pl_cb; 
} PAGELIST; 
typedef PAGELIST *PPAGELIST; 
// RPstatus bit values 
define RPERR 0x8000 // error occurred, err in RPstatus 
define RPDEV 0x4000 // error code defined by driver 
define RPBUSY 0x0200 // device is busy 
define RPDONE 0x0100 // ariver done with request packet 


// error codes returned in RPstatus 











define ERROR_WRITE_PROTECT 0x0000 
define ERROR_BAD_UNIT 0x0001 
define ERROR_NOT_READY 0x0002 
define ERROR_BAD_COMMAND 0x0003 
define ERROR_CRC 0x0004 
define ERROR_BAD_LENGTH 0x0005 
define ERROR_SEEK 0x0006 
define ERROR_NOT_DOS_DISK 0x0007 
define ERROR_SECTOR_NOT_FOUND 0x0008 
define ERROR_OUT_OF_PAPER 0x0009 


define ERROR_WRITE_FAULT 
define ERROR_READ_FAULT 
define ERROR_GEN_FAILURE 
define ERROR_DISK_CHANGE 
define ERROR_WRONG_DISK 
define ERROR_UNCERTAIN_MEDIA 


define ERROR_NO_MONITOR_SUPPORT 
define ERROR_INVALID_PARAMETER 
define ERROR_DEVICE_IN_USE 
define ERROR_QUIET_FAIL 








define RPINIT 0x00 
define RPMEDIA_CHECK 0x01 
define RPBUILD_BPB 0x02 
define RPREAD 0x04 


define RPREAD_NO_WAIT 0x05 
define RPINPUT_STATUS 0x06 
define RPINPUT_FLUSH 0x07 
define RPWRITE 0x08 
define RPWRITE_VERIFY 0x09 
define RPOUTPUT_STATUS 0x0a 


define RPOUTPUT_FLUSH 0x0b 








define RPOPEN Ox0d 
define RPCLOSE Ox0e 
define RPREMOVABLE Ox0f 
define RPIOCTL 0x10 
define RPRESET Ox 


1 
define RPGET_DRIVE_MAP 0x12 
define RPSET_DRIVE_MAP 0x13 
define RPDEINSTALL 0x14 
define RPPARTITIONABLE 0x16 
define RPGET_FIXED_MAP 0x17 
define RPSHUTDOWN Oxlc 
define RPGET_DRIVER_CAPS 0x 
define RPINIT_COMPLETE Oxlf 


1d 














define MON_OPEN_STATUS 0x08 
define MON_CLOSE_STATUS 0x08 


// media descriptor byte 


define MDB_REMOVABLE 0x04 
define MDB_EIGHT_SECTORS 0x02 
define MDB_DOUBLE_SIDED 0x01 


// veturn codes from MediaCheck 


define MC_MEDIA_UNCHANGED 0x01 
define MC_MEDIA_CHANGED OxFF 
define MC_MEDIA_UNSURE 0x00 


// event numbers for SendEvent 


define EVENT_SM_MOUSE 0x00 
define EVENT_CTRLBRK 0x01 
define EVENT_CTRLC 0x02 
define EVENT_CTRLNUMLK 0x03 
define EVENT_CTRLPRTSC 0x04 








Ox000A 
0x000B 
0x000C 
0x000D 
Ox000F 
0x0010 


define ERROR_CHAR_CALL_INTERRUPTED 0x0011 


0x0012 
0x0013 
0x0014 
0x0015 


// driver request codes B=block, C=character 


// BC 
// B 
// B 
// BC 
// cC 
// Cc 
// Cc 
// BC 
// BC 
// G 
Lf C 
// BC 
// BC 
// B 
// BC 
// B 
// B 
// B 
// or 
// B 
// B 
// BC 
// B 
// BC 


// check for monitor call in DosOpen/DosClose 


// open from DosMonOpen 
// close from DosMonClose 


//  1=removable 
// 1=8 sectors per track 
// 1=double-sided media 


// session 
// control 
// control 
// control 
// control 


switch via mouse 
break 

Cc 

num lock 
printscreen 


define EVENT_SHFTPRTSC 
define EVENT_SM_KBD 


0x05 
0x06 


// 
// 


// defines for 1.x movedata function 











shift printscreen 
session switch hot key 


from 
from 
from 
from 


define MOVE_PHYSTOPHYS 0 // move bytes 
define MOVE_PHYSTOVIRT 1 // move bytes 
define MOVE_VIRTTOPHYS 2 // move bytes 
define MOVE_VIRTTOVIRT 3 // move bytes 
// Micro Channel specific 

int GetLIDEntry (USHORT, USHORT, USHORT, PUSHORT) ; 
int FreeLIDEntry (USHORT); 

int ABIOSCall (USHORT, USHORT, PVOID); 

int ABIOSComm (USHORT, PVOID); 

int GetDeviceBlock (USHORT, PVOID); 

// special routines 

void INT3 (void); 

void Enable (void) ; 

void Disable (void); 

void Abort (void); 

int SegLimit (SEL, PFUNCTION *); 

int MoveBytes (PVOID,PVOID,USHORT) ; 

int MoveData (PVOID, PVOID, USHORT, USHORT); 

// system services and misc. 

int GetDOSVar (USHORT, PPVOID); 

int SendEvent (USHORT, USHORT); 

void SchedClockAddr (PPVOID); 

int AttachDD (PSTRING, PATTACHAREA) ; 

int InternalError (PSTRING, USHORT) ; 

int SaveMessage (PSTRING) ; 

int ProtToReal (void); 

int RealToProt (void); 

int SetROMVector (USHORT, PFUNCTION, PFUNCTION, PVOID) ; 





// process mgmt 


USHORT) ; 


PLHANDLE) ; 


void Yield (void); 

void TCYield (void); 

int Block (ULONG, ULONG, USHORT, PVOID); 
void Run (ULONG) ; 

void DevDone (PREQPACKET) ; 

int VideoPause (USHORT) ; 

// memory management 

int AllocPhys (ULONG, USHORT, PPHYSADDR) ; 
int FreePhys (PHYSADDR) ; 

int VerifyAccess (SEL, OFFSET, USHORT, 
int LockSeg (SEL, USHORT, USHORT, 

int UnLockSeg (LHANDLE) ; 








// address conversion 





phys 
phys 
virt 
virt 


int AllocGDTSelector(USHORT, PVOID); 

int PhysToGDTSelector(PHYSADDR, USHORT, SEL, PERRCODE) ; 
int VirtToPhys (PVOID, PPHYSADDR) ; 

int PhysToUVirt (PHYSADDR, USHORT, USHORT, PVOID); 


to 
to 
to 
to 


phys 
virt 
phys 
virt 


memory 
memory 
memory 
memory 


int 
int 


PhysToVirt (PHYSADDR, USHORT, 
UnPhysToVirt (void); 


// request packet queue stuff 


int 
void 
void 
void 
int 
int 


AllocReqPacket 
FreeReqPacket 
PushReqPacket 
SortReqPacket 
PullReqPacket 
PullParticular 


(USHORT, 
(PREQPACKET) ; 
(PQHEAD, 
(PQHEAD, 
(PQHEAD, 

(PQHEAD, 


// driver semaphores 
int SemHandle (LHANDLE, 


int SemRequest (LHANDLE, 
void SemClear (LHANDLE) ; 


FLAG, 
ULONG, 


// circular character queues 


void QueuelInit 
void QueueFlush (PCHARQUEUE) ; 
int QueueWrite (PCHARQUEUE, 
QueueRead (PCHARQUEUE, 


(PCHARQUEUE) ; 


UCHAR) ; 
int PUCHAR) ; 


// interrupt stuff 





SetIRQ (USHORT, 
UnSetIRQ (USHORT) ; 

EOL (USHORT) ; 

void ClaimInterrupt (void) ; 
void RefuseInterrupt (void) ; 


pe 
i: 
ck ct 














USHORT, 


PPREQPACKET) ; 


PREQPACKET) ; 
PREQPACKET) ; 
PPREQPACKET) ; 
PREQPACKET) ; 


PLHANDLE) ; 
PERRCODE) ; 


PFUNCTION, USHORT) ; 


PVOID) ; 











int RegisterStackUsage (PREGSTACK) ; 

// timer stuff 

int SetTimer (PFUNCTION) ; 

int ResetTimer (PFUNCTION) ; 

int TickCount (PFUNCTION, USHORT) ; 

// device monitors 

int MonCreate (PSHANDLE, PVOID, PVOID, PERRCODE) ; 

int Register (SHANDLE, USHORT, PID, PVOID, PFUNCTION, PERRCODE) ; 
int MonWrite (SHANDLE, PVOID, USHORT, USHORT, ULONG, PERRCODE) ; 
int MonFlush (SHANDLE, PERRCODE) ; 

int DeRegister (SHANDLE, PID, PERRCODE) ; 

// 2.% specfic 

int RegisterPDD (PUCHAR, PFUNCTION) ; 

int RegisterBeep (PFUNCTION) ; 

int Beep (USHORT,USHORT) ; 

int FreeGDTSelector(USHORT) ; 

int PhysToGDTSel (PHYSADDR, ULONG, SEL, USHORT, PUSHORT) ; 
int VMLock (LINADDR, ULONG, LINADDR, LINADDR, ULONG, PULONG) ; 
int VMUnlock (LHANDLE) ; 

int VMAlloc(LINADDR, ULONG, ULONG, PLINADDR) ; 

int VMFree (PHYSADDR) ; 

int VMProcessToGlobal (LINADDR, ULONG, ULONG, PLINADDR) ; 
int VMGlobalToProcess (LINADDR, ULONG, ULONG, PLINADDR) ; 
int VirtToLin(PVOID, PLINADDR) ; 

int LinToGDTSelector (SEL, LINADDR, ULONG) ; 


in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 
in 


eRe ch ct cho ct chick ote ct et 





aoe ct 


// 


in 
in 
in 
in 
in 


atddtaec 


int 
int 
// 
in 
in 
in 
in 





Chock ‘cect 


GetDescInfo (SEL, PUSHORT, PULONG, PULONG) ; 
LinToPageList (LINADDR, ULONG, LINADDR, PULONG) ; 
PageListToLin (ULONG, LINADDR, PLINADDR) ; 
PageListToGDTSelector (SEL, ULONG, LINADDR, USHORT, PUSHORT) ; 
RegisterTmrDD (PFUNCTION, PPVOID, PPVOID) ; 
AllocCtxHook (PFUNCTION, ULONG, PLHANDLE) ; 


FreeCtxHook (LHANDLE) ; 


ArmCtxHook (ULONG, LHANDLE, ULONG) ; 
VMSetMem (LINADDR, ULONG, ULONG) ; 


OpenEvent Sem (LHANDLE) ; 
CloseEventSem (LHANDLE) ; 
PostEventSem (LHANDLE) ; 


ResetEventSem(LHANDLE, LINADDR) ; 


DynamicAPI (PVOID, USHO 
SMP DevHlps 


CreateSpinLock (PHSPINLOCK) ; 
FreeSpinLock (HSPINLOCK) ; 
AcquireSpinLock (HSPINLOCK) 
ReleaseSpinLock (HSPINLOCK) 
PortIO(PPORTIO_STRUCT) ; 


’ 
’ 


Set IRQMask (USHORT, USHORT) ; 
Get IRQMask (USHORT, PVOID) ; 





APM 


APMInit (PVOID) ; 
APMDeReg (PVOID) ; 
NoError(); 
GetMachine(PVOID) ; 


RT, USHORT, PUSHORT) ; 


// these are the only API's available to the driver at Init time 


de 


C 
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fine APIENTRY 
ORT APIENTRY DosBeep(USHORT, USHORT); 
ORT APIENTRY DosCaseMap(USHORT, PVOID, PVOID); 
ORT APIENTRY DosChgFilePtr(SHANDLE, long, USHORT, PVOID); 
ORT APIENTRY DosClose(SHANDLE) ; 
ORT APIENTRY DosDelete(PVOID, ULONG); 
ORT APIENTRY DosDevConfig(PVOID, USHORT, USHORT); 
ORT APIENTRY DosDevIOCtl(PVOID, PVOID, USHORT, USHORT, USHORT) ; 
ORT APIENTRY DosFindClose (SHANDLE) ; 
ORT APIENTRY DosFindFirst (PVOID, PVOID, USHORT, PVOID, 
USHORT, PVOID, ULONG); 
ORT APIENTRY DosFindNext (SHANDLE, PVOID, USHORT, PVOID); 
ORT APIENTRY DosGetEnv(PVOID, PVOID); 
ORT APIENTRY DosGetMessage(PVOID, USHORT, PVOID, USHORT, 
USHORT, PVOID, PVOID); 
ORT APIENTRY DosOpen(PVOID, PVOID, PVOID, ULONG, 
USHORT, USHORT, USHORT, ULONG) ; 


HORT APIENTRY DosPutMessage(SHANDLE, USHORT, PVOID); 

HORT APIENTRY DosQCurDir(USHORT, PVOID, PVOID); 

HORT APIENTRY DosQCurDisk(PVOID, PVOID); 

HORT APIENTRY DosQFileInfo(SHANDLE, USHORT, PVOID, USHORT) ; 
[T APIENTRY DosQFileMode(PVOID, PVOID, ULONG) ; 

HORT APIENTRY DosRead(SHANDLE, PVOID, USHORT, PVOID); 

HORT APIENTRY DosWrite(SHANDLE, PVOID, USHORT, PVOID); 

HORT APIENTRY DosCreateSpinLock (PHSPINLOCK) ; 

HORT APIENTRY DosFreeSpinLock (HSPINLOCK) ; 
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// end of DRVLIB.H 


Figure A-4. Driver library header file, 32-bit. 


#include "drvlib.h" 
#include "digio.h" 


int main(PREQPACKET rp); 


DEVICEHDR devhdr = 
{ 








(void *) OXxFFFFFFFF, /* Link fh 
(DAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute word */ 
&main, /* &strategy */ 
0, /* &IDC routine */ 
"DIGIOS " /* name/#units a 
‘i 
PFUNCTION DevH1lp=0; /* pointer to DevHlp entry point */ 
UCHAR opencount = 0; /* keeps track of open's ay 
USHORT savepid=0; /* save thread pid */ 
LHANDLE lock_seg_han; /* handle for locking appl. seg */ 
PHYSADDR appl_buffer=0; /* address of caller's buffer af 
ERRCODE err=0; /* error return ef 
ULONG ReadID=0OL; /* current read pointer */ 
USHORT num_rupts=0; /* count of interrupts */ 
USHORT temp_char; /* temp character for in-out */ 
void ovr; /* temp pointer ef 
PVOID appl_ptr=0; /* pointer to application buffer */ 
char input_char,output_char; /* temp character storage */ 
char input_mask; /* mask for input byte ef 


/* messages */ 


char CrLf[]= "\r\n"; 

char InitMessagel[] = " 8 bit Digital I/O "; 

char InitMessage2[] = " driver installed\r\n"; 

char FailMessage[] = " driver failed to install.\r\n"; 


/* common entry point for calls to Strategy routines */ 

int main(PREQPACKET rp) 

{ 
Void *ptr; 
PLINFOSEG liptr; /* pointer to global info seg */ 
int i; 


switch (rp->RPcommand) 


{ 
case RPINIT: /* 0x00 * 


/* init called by kernel in protected mode */ 
return Init (rp); 


case RPREAD: /* 0x04 */ 
rp->s.ReadWrite.count = 0; /* in case we fail */ 
input_char = inp(DIGIO_INPUT);/* get data st 
if (PhysToVirt( (ULONG) rp->s.ReadWrite.buffer, 
1,0,&appl_ptr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes ((PVOID) &input_char,appl_ptr,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
rp->s.ReadWrite.count = 1; /* one byte read */ 
return (RPDONE); 
case RPWRITE: /* 0x08 ay. 
rp->s.ReadWrite.count = 0; 
if (PhysToVirt( (ULONG) rp->s.ReadWrite.buffer, 
1,0,&appl_ptr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes (appl_ptr, (PVOID) &0utput_char,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
outp (DIGIO_OUTPUT, output_char); /* send byte xf 
rp->s.ReadWrite.count = 1; /* one byte written mf 
return (RPDONE); 
case RPOPEN: /* 0x0d open driver */ 


/* get current process id */ 


if 


(GetDOSVar (2, &ptr) ) 


return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
/* get process info */ 








liptr = *((PLINFOSEG *) ptr); 

/* if this device never opened, can be opened by anyone*/ 
if (opencount == 0) /* first time this dev opened */ 
opencount=1; /* bump open counter e/ 
savepid = liptr->pidCurrent; /* save current PID ¥y 

else 
if (savepid != liptr->pidCurrent) /* another proc */ 
return (RPDONE | RPERR | ERROR_NOT_READY) ;/*err*/ 
++opencount; /* bump counter, same pid * 
return (RPDONE) ; 
case RPCLOSE: /* Ox0e DosClose,ctl-C, kill */ 
/* get process info of caller */ 
if (GetDOSVar (2,é&ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
/* get process info from os/2 */ 
liptr= *((PLINFOSEG *) ptr); /* ptr to linfoseg */ 
/* 
make sure that process attempting to close this device 
is the one that originally opened it and the device was 
open in the first place. 
*/ 
if (savepid != liptr->pidCurrent || opencount == 0) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
—-opencount; /* close counts down open cntr*/ 
return (RPDONE) ; /* return 'done' status *f 
case RPIOCTL: /* 0x10 */ 


/* 


The function code in an IOCtl packet has the high bit set 
for the DIGIOS board. We return all others with the done 
bit set so we don't have to handle things like the 5-48 
code page IOctl 

ved 

if (rp->s.I0Ctl.category != DIGIO_CAT)/* other IOCtls */ 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

switch (rp->s.IOCtl.function) 

{ 





case 0x01: /* write byte to digio port ey 
/* verify caller owns this buffer area */ 
if (VerifyAccess ( 


SELECTOROF (rp->s.IOCtl.parameters), /* selector add 
OFFSETOF (rp->s.IOCtl.parameters), /* offset a 
ity /* 1 byte bad 
0) } /* read only */ 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes (rp->s.IOCtl.parameters, (PVOID) 
é&output_char,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
outp (DIGIO_OUTPUT, output_char) ; /*send to digio*/ 
return (RPDONE) ; 





case 0x02: /* read byte w/wait from port */ 
/* verify caller owns this buffer area */ 
if (VerifyAccess{ 


SELECTOROF (rp->s.IOCtl.buffer), /* selector */] 
OFFSETOF (rp->s.I10Ctl.buffer), /* offset */ 
iy /* 1 bytes) ial J 
0) ) /* read only */ 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 











if (LockSeg ( 
SELECTOROF (rp->s.10Ctl.buffer), /* selector xf 
1, /* lock forever */ 
0, /* wait for seg loc*/ 
(PLHANDLE) &lock_seg_han) ) /* handle returned */ 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (MoveBytes (rp->s.IOCtl.parameters, (PVOID) 
é&input_mask,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 





/* wait for switch to be pressed */ 


ReadID = (ULONG) rp; /* block ID */ 
if (Block (ReadID,-1L,0,éerr) ) 
if (err == 2) 


return(RPDONE | RPERR 
| ERROR_CHAR_CALL_INTERRUPTED) ; 
/* move data to users buffer */ 
if (MoveBytes ((PVOID) &input_char,rp->s.IOCtl.buffer, 
1)) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* unlock segment */ 
if (UnLockSeg (lock_seg_han) ) 

return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
return (RPDONE); 











case 0x03: /* read byte immed digio port */ 
/* verify caller owns this buffer area */ 

if (VerifyAccess ( 

SELECTOROF (rp->s.I10Ctl.buffer), /* selector otf 





OFFSETOF (rp->s.I0Ctl.buffer), /* offset ee] 
4, /* 4 bytes xf 
0) ) /* read only */ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


input_char = inp(DIGIO_INPUT); /* get data at A 
if (MoveBytes ((PVOID) &input_char, rp->s.IOCtl.buffer,1) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


return (RPDONE); 


default: 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
} 


/* don't allow deinstall */ 
case RPDEINSTALL: fe Oxia */ 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


/* all other commands are flagged as bad */ 
default: 
return (RPDONE RPERR | ERROR_BAD_COMMAND) ; 


timr_handler () 


{ 


if (ReadID != 0) { 
/* read data from port */ 
input_char = inp(DIGIO_INPUT );/* get data ef 
if ((input_char && input_mask) !=0) { 
Run (ReadID) ; 
ReadID=0L; 


} 
} 
/* Device Initialization Routine */ 


int Init (PREQPACKET rp) 
{ 
/* store DevHlp entry point */ 
DevHlp = rp->s.Init.DevHlp; 
/* install timer handler */ 
if (SetTimer((PFUNCTION)timr_handler)) { 
/* if we failed, effectively deinstall driver with cstds=0 */ 
DosPutMessage(1, 8, devhdr.DHname) ; 
DosPutMessage(1,strlen(FailMessage) ,FailMessage) ; 
rp->s.InitExit.finalCS = (OFFSET) 0; 
rp->s.InitExit.finalDS = (OFFSET) 0; 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
} 


/* configure 8255 parallel chip */ 

outp (DIGIO_CONFIG, 0x91); 

/* output initialization message */ 

DosPutMessage(1l, 2, CrLf); 

DosPutMessage(1l, 8, devhdr.DHname) ; 

DosPutMessage(1, strlen(InitMessagel), InitMessagel1) ; 
DosPutMessage(1, strlen(InitMessage2), InitMessage2) ; 


/* send back our code and data end values to os/2 */ 
if (SegLimit (HIUSHORT((void *) Init), 


&rp->s.InitExit.finalcs) || SegLimit (HIUSHORT((void *) 
InitMessage2), &rp->s.InitExit.finalDS) ) 
Abort (); 


return (RPDONE) ; 


Figure A-5. Simple OS/2 parallel device driver, 32-bit version. 


#include "drvlib.h" 
#include "mmap.h" 


extern void near STRATEGY (); // name of strat rout. in DDSTART 


DEVICEHDR devhdr = { 

















(void far *) OxFFFFFFFF, // link 

(DAW_CHR | DAW_OPN | DAW_LEVEL1),// attribute 

(OFF) STRATEGY, // &strategy 

(OFF) 0, // &IDCroutine 

"MMAP s " 
hi 
FPFUNCTION DevHlp=0; // storage area for DevHlp calls 
LHANDLE lock_seg_han; // handle for locking appl. segment 
PHYSADDR appl_buffer=0; // address of caller's buffer 
PREQPACKET p=OL; // pointer to request packet 
ERRCODE err=0; // error return 
void far *ptr; // temp far pointer 
USHORT ip // general counters 
PHYSADDR board_address; // base board address 
USHORT opencount; // count of DosOpens 
USHORT savepid; // save the caller's PID 
USHORT cntr = 0; // misc counter 
USHORT bus = 0; // default ISA bus 
REQBLK ABIOS_r_blk; // ABIOS request block 
LIDBLK ABIOS_1_b1k; // ABIOS LID block 
USHORT lid_blk_size; // size of LID block 
CARD card[MAX_NUM_SLOTS+1]; // array for IDs 
CARD *pcard; // pointer to card array 
USHORT matches = 0; // match flag for card ID 
POS_STRUCT pos_struct; // struct to get POS reg 
ADDR_STRUCT addr_struct; // struct for passing addresses 
USHORT chunk1, chunk2; // temp variables for address calc 
char arguments[64]={0}; // save command line args in dgroup 
char NoMatchMsg[] = " no match for selected Micro Channel 

card ID found.\r\n"; 
char MainMsgMCA[] = "\r\nOS/2 Micro Channel memory-mapped 
driver installed.\r\n"; 

char MainMsgISA[] = "\r\nOS/2 ISA bus memory-mapped driver 


installed.\r\n"; 


// pro 
int 

USHORT 
UCHAR 
UCHAR 


totypes 
hex2bin(char c); 
get_POS(); 


get_pos_data(); 
nget_pos_data(); 


// common entry point for calls to Strategy routines 


int ma 


{ 


in(PREQPACKET rp ) 


void far *ptr; 


int 
PLIN 
int 
ULON 
USHO 


swit 
{ 


ca 


ca 


ca 








far *pptr; 

FOSEG liptr; // pointer to local info seg 

i; 

G addr; 

RT in_data; 

ch (rp->RPcommand) 

se RPINIT: // 0x00 

// init called by kernel in protected mode ring 3 with IOPL 

return Init (rp); 

se RPOPEN: // 0x0d 

// get current processes id 

if (GetDOSVar (2,é&ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

// get process info 

liptr = *((PLINFOSEG far *) ptr); 

// if this device never opened, can be opened by any process 

if (opencount == 0) // first time this device opened 
opencount=1; // set open counter 
savepid = liptr->pidCurrent; // save current process id 

else 
if (savepid != liptr->pidCurrent) // proc tried to open 

return (RPDONE | RPERR | RPBUSY ); // so return error 

++opencount; // bump counter, same pid 

return (RPDONE); 

se RPCLOSE: // O0x0e 


// get process info of caller 
if (GetDOSVar (2,&ptr) ) 

return (RPDONE | RPERR | ERROR_BAD_COMMAND); // no info 
// get process info from os/2 
liptr= *((PLINFOSEG far *) ptr); // ptr to process info seg 
// 
// make sure that process attempting to close this device 
// one that originally opened it and the device was open in 
// first place. 
// 
if (savepid != liptr->pidCurrent | | opencount == 0) 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
// if an LDT selector was allocated, free it 
PhysTouUVirt (board_address, 0x8000,2, 

(FARPOINTER) &addr_struct .mapped_addr) ; 

--opencount; // close counts down open counter 
return (RPDONE) ; // veturn 'done' status to caller 


case RPREAD: // 0x04 
return (RPDONE) ; 


case RPWRITE: // 0x08 
return (RPDONE) ; 


case RPIOCTL: // 0x10 
if (rp->s.I0Ctl.category != OUR_CAT) // only our category 
return (RPDONE); 


switch (rp->s.IOCtl.function) 
{ 
// this IOCtl returns the bus type. If Micro Channel 
// the return is Oxff01. If ISA, the return is ff00 


case 0x01: // check if MCA or ISA 
return (RPDONE | RPERR | bus); 


// this IOCtl maps adapter mem to an LDT selector:offset, 
// and sends it to the application for direct reads 
// and writes 


case 0x02: // send memmapped addr to app 
// verify caller owns this buffer area 
if (VerifyAccess ( 
SELECTOROF (rp->s.IO0Ctl.buffer), // selector 
OFFSETOF (rp->s.I0Ctl.buffer), // offset 
8, // 8 bytes 
1) ) // read write 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// lock the segment down temp 


if (LockSeg ( 
SELECTOROF (rp->s.IO0Ctl.buffer), // selector 
0% // lock < 2 sec 
0, // wait for seg lock 
(PLHANDLE) &lock_seg_han) ) // handle returned 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// map the board address to an LDT entry 
if ( PhysToUVirt (board_address,0x8000,1, 
(FARPOINTER) &addr_struct .mapped_addr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// move data to users buffer 
if (MoveBytes ( 


é&addr_struct, // source 
rp->s.10Ctl.buffer, // dest 
8) ) // 8 bytes 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// unlock segment 
if (UnLockSeg (lock_seg_han) ) 

return (RPDONE RPERR | ERROR_GEN_FAILURE) ; 
return (RPDONE) ; 





// this IOCtl demonstrates how an application gets the 
// contents of a Micro Channel Adapter's POS registers 


case 0x03: // get pos reg data 
// verify caller owns this buffer area 
if (VerifyAccess ( 
SELECTOROF (rp->s.I0Ctl.buffer), // selector 


OFFSETOF (rp->s.10Ctl.buffer), 


6, 
1) ) 


// lock the segment down temp 


if (LockSeg ( 


SELECTOROF (rp->s.1I0Ctl. buffer), 


0, 
0, 


(PLHANDLE) 


&lock_seg_han) ) 


// offset 

// 6 bytes 

// vead write 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// selector 

// lock < 2 sec 

// wait for seg lock 
// handle returned 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// move slot data to driver buffer 


if (MoveByte 


(FARPOINTER) 


s ( 


&pos_struct, 


6)) 


pos_struct. 


data 


appl_buffer, 


// source 
// for pos data 
// 6 bytes 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


get_pos_data(pos_struct.slot,pos_struct.reg) ; 
// move POS reg data to users buffer 


if (MoveByte 
&pos_stru 
(FARPOINT 
6)) 


// unlock s 


Ss ( 
City, 
ER) 


egment 


appl_buffer, 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


return (RPD 


case 0x04: 
// verify c 
if (VerifyAc 
SELECTORO 
OFFSETOF ( 
8, 
1) ) 
return (R 
// lock the 
if (LockSeg ( 
SELECTORO 
0, 
0, 
(PLHANDLE 
return (R 


// map the board addres 
UVirt (board_ 
(FA 


if ( PhysTo 
return (R 
// now conv 
if 


return (R 


ONE); 


this IOCtl is the same as 0x02, 
user virtual address is mapped to a lin address 
process address range and then sent to the app. 
saves the SelToFlat and FlatToSel each time the ptr is 
referenced. 


// for pos data 
// source 

// 6 bytes 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


except tle 


This 


// 32-bit memory-mapped addr to app 


aller owns 
cess ( 
F(rp->s.I0OC 
rp->s.Ioctl 


PDONE | RPE 
segment do 


F(rp->s.I0OC 


Pp 


DONE RPE 


RPOINTE 
DONE 
ert it 


R 
RPE 
toa 


Pp 


(VirtToLin ( (FARPOINTER) addr 


(PLINAD 
DONE 


DR) 
RPE 














Pp 


) &lock_seg_ 


tl.buffer), 
-buffer), 


wn temp 


tl.buffer), 


han) ) 
R E 
s to 

addre 


R RO 
an 
s 
RR ER 


linear 


RO 


& 
R 


addr_ 
R E 


s 
R 




















RO 


// move data to users buffer 


if (MoveByte 


s ( 


R_GEN_ 
LDT en 
s,0x8000,1, 
é&addr_struct.mapped_ 
R_GEN_ 
address 
struct 
truct.ma 
R_GEN_ 


this buffer area 


// se 


// offset 


Le 


ctor 


// 8 bytes 
// vead write 


RR | ERROR_GEN_FA 


// se 


Le 


[LU 


RE) ; 


ctor 


// lock < 2 sec 
// wait 
// handle returned 


FA 


FA 





FA 


try 


[L 


cL 





cL 


for seg lock 


RE) ; 


addr) ) 
RE) ; 


-mapped_addr, 
pped_addr) ) 











RE) ; 


in the 


é&addr_struct, // source 
rp->s.10Ctl.buffer, // dest 

8) ) // 8 bytes 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// unlock segment 
if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
return (RPDONE); 
} // switch (rp->s.IOCtl. function 


case RPDEINSTALL: // 0x14 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


// all other commands are ignored 
default: 
return (RPDONE) ; 


int hex2bin(char c) 


{ 
if(c < 0x3a) 


return (c — 48); 
else 
return (( c & Oxdf) - 55); 


USHORT get_POS(USHORT slot_num, 
USHORT far *card_ID, 
UCHAR far *pos_regs) 

{ 

USHORT rc, i, lid; 


if (GetLIDEntry(0x10, 0, 1, &lid)) // get LID for POS 
return (1); 


// Get the size of the LID request block 
ABIOS_1_blk.f_parms.req_blk_len = sizeof(struct lid_block_def) ; 
ABIOS_1_blk.f_parms.LID = lid; 
ABIOS_1_blk.f_parms.unit = 0;; 
ABIOS_1_blk.f_parms.function = GET_LID_BLOCK_SIZE; 
ABIOS_1_b1lk.f_parms.ret_code = 0x5a5a; 
ABIOS_1_blk.f_parms.time_out = 0; 
if (ABIOSCall(lid,0, (void far *) &ABIOS_1_b1k) ) 

return (1); 
lid_blk_size = ABIOS_1 blk.s_parms.blk_size; // Get block size 
// Fill POS regs and card ID with FF in case this does not work 
*card_ID = OxFFFF; 
for (i=0; i<NUM_POS_BYTES; i++) { pos_regs[i] = 0x00; }; 
// Get the POS registers and card ID for the commanded slot 














ABIOS_r_blk.f_parms.req_blk_len = lid_blk_size; 
ABIOS_r_blk.f_parms.LID = lid; 
ABIOS_r_blk.f_parms.unit = 0;; 
ABIOS_r_blk.f_parms.function = READ_POS_REGS_CARD; 
ABIOS_r_blk.f_parms.ret_code = 0x5a5a; 
ABIOS_r_blk.f_parms.time_out = 0; 
ABIOS_r_blk.s_parms.slot_num = (UCHAR)slot_num & Ox0OF; 
ABIOS_r_blk.s_parms.pos_buf = (void far *)pos_regs; 
ABIOS_r_blk.s_parms.card_ID = OxFFFF; 


if (ABIOSCall(lid,0, (void far *) &ABIOS_r_blk) ) 
Ke. =. 1; 
else 


{ // Else 


*card_ID = ABIOS_r_blk.s_parms.card_ID; // Set card ID value 


re = 0; 
} 
FreeLIDEntry (lid); 
return(rc); 


UCHAR get_pos_data (int slot, int reg) 
{ 

UCHAR pos; 

CARD *cptr; 


cptr = &card[slot-1]; // set ptr to card array 
if (reg == 0) // card ID 
pos = LOUSHORT (cptr->card_ID) ; 
else 
if ( reg == 1) 
pos = HIUSHORT(cptr->card_ID); 
else 


pos = cptr->pos_regs[reg-2]; // POS data register 
return (pos); 


} 
// Device Initialization Routine 


int Init (PREQPACKET rp) 
{ 

USHORT lid; 

register char far *p; 


// store DevHlp entry point 
DevHlp = rp->s.Init.DevHlp; // save DevHlp entry point 
if (!(GetLIDEntry (0x10, 0, 1, &lid))) 
{ // get LID for POS 
FreeLIDEntry (lid); 
// Micro Channel (tm) setup section 
bus = 1; // MCA bus 


// Get POS data and card ID for each of 8 possible slots 


for (i=0;i <= MAX_NUM_SLOTS; i++) 
get_POS(it+1, (FARPOINTER) écard[i].card_ID, 
(FARPOINTER) card[i].pos_regs) ; 
matches = 0; 
for (i=0, pcard = card; i <= MAX_NUM_SLOTS; i++, pcard+t+) 
{ 


if (pcard->card_ID == TARGET_ID) 
{ 
matches = 1; 
break; 
} 
} 
if (matches == 0) { // at least one board found 


DosPutMessage(1l, 8, devhdr.DHname) ; 
DosPutMessage(1,strlen(NoMatchMsg) ,NoMatchMsg) ; 
rp->s.InitExit.finalCS = (OFF) 0; 
rp->s.InitExit.finalDS = (OFF) 0; 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
} 
// calculate the board address from the POS regs 
board_address = ((unsigned long) get_pos_data(i+l, 4) 
<< 16) | ((unsigned long) (get_pos_data(i+l, 3) & 1) 
<< 15); 


#i 
#i 
// 


else 
// ISA bus setup 
{ 


bus 


0; 


// get parameters, 


for (p = rp->s.Init.args; 
for (; *p == ' '; ++p); 
if (*p) 


{ 
board_address=0; 
for (; *p T\O5G 
board_address 
addr_struct.board_addr 


++p) 


} 


if (bus) 


(board_address << 4) 


// ISA bus 


port addr and base mem addr 


*p && *p t= ' ';+tp); 


// skip blanks following name 


// i/o port address 

// get board address 

+ (hex2bin(*p)); 
board_address; 


DosPutMessage (1, strlen (MainMsgMCA) ,MainMsgMCA) ; 


else 


DosPutMessage (1, strlen (MainMsgISA) ,MainMsgISA) ; 


// send back our cs and ds end values to os/2 


if (SegLimit (HIUSHORT((void far *) Init), 
&rp->s.InitExit.finalcs) || 
SegLimit (HIUSHORT((void far *) MainMsgISA), 
&rp->s.InitExit.finalDS) ) 
Abort (); 


Beep (200, 500) 

Beep (200,500); 

Beep (250,500); 
) 
) 


7 


’ 


Beep (300,500 
Beep (250,500); 
Beep (300,500); 
return (RPDONE) ; 


Figure A-6. Memory-mapped device driver, 16-bit version. 


nclude <stdio.h> 
nclude <string.h> 


OS/2 Device Driver for memory mapped I/O 


Steve Mastri 
15 Great Oak 
Unionville, 

(203) 693-04 
(203) 693-90 
CIS 71501,16 
BIX smastria 
Internet 609 


This driver is loaded in the config.sys file with the DEVICE= 
For ISA configuration, 


statement. 
is the board base memory 


anni 
Lane 
CT 06085 
04 voice 
42 data 
52 
nni 
9225@mcimail.com 


the first parameter to the 
address in hex. 


"DEVICE=" 


This driver also returns a boolean to the calling application to 


inform it of the bus type 


(Micro Channel or ISA). 


// All numbers are in hex. For MCA configuration, the board address 
if is read from the board POS regs. The POS regs data is specific for 
// each adapter, so the address calculations here may not work with 
// your specific adapter. Refer to the hardware tech reference for the 
// particular adapter to determine where and how the address appears 
// in the POS registers. 

// 

// 

// This driver allows the application I/O to run in Ring 2 with IOPL. 
// The CONFIG.SYS files *must* contain the IOPL=YES statement. 

// 

// This driver supports 4 IOCtls, Category 0x90. 

// 

// IOCtl 0x01 test for MCA or ISA bus 

// IOCtl 0x02 gets and returns a selector to fabricated board memory 
// TOCtl 0x03 gets the value of a selected POS register 

// TOCtl 0x04 gets the board address that the driver found 

// 

// The driver is made by using the make file mmap.mak. 





#include "drvlib.h" 
#include "mmap.h" 


extern void STRATEGY(); // name of strat rout. in DDSTART 


DEVICEHDR devhdr = { 

















(void *) OxFFFFFFFF, // link 

(DAW_CHR | DAW_OPN | DAW_LEVEL1),// attribute 

(OFF) STRATEGY, // &strategy 

(OFF) 0, // &IDCroutine 

"MMAP s " 
‘i 
FPFUNCTION DevHlp=0; // storage area for DevHlp calls 
LHANDLE lock_seg_han; // handle for locking appl. segment 
PHYSADDR appl_buffer=0; // address of caller's buffer 
PREQPACKET p=OL; // pointer to request packet 
ERRCODE err=0; // error return 
void *ptry // temp pointer 
USHORT diss // general counters 
PHYSADDR board_address; // base board address 
USHORT opencount; // count of DosOpens 
USHORT savepid; // save the caller's PID 
USHORT entr = 0; // misc counter 
USHORT bus = 0; // default ISA bus 
REQBLK ABIOS_r_blk; // ABIOS request block 
LIDBLK ABIOS_1_b1k; // ABIOS LID block 
USHORT lid_blk_size; // size of LID block 
CARD card[MAX_NUM_SLOTS+1]; // array for IDs and POS reg values 
CARD *pcard; // pointer to card array 
USHORT matches = 0; // match flag for card ID 
POS_STRUCT pos_struct; // struct to get POS reg 
ADDR_STRUCT addr_struct; // struct for passing addresses 
USHORT chunk1, chunk2; // temp variables for address calc 
char arguments [64]={0}; // save command line args in dgroup 
char NoMatchMsg[] = " no match for selected Micro Channel card ID 
found. \r\n"; 
char MainMsgMCA[] = "\r\nOS/2 Micro Channel memory-mapped driver 
installed.\r\n"; 
char MainMsgISA[] = "\r\nOS/2 ISA bus memory-mapped driver installed.\r\n"; 





// prototypes 


int hex2bin(char c); 
USHORT get_POS(); 

UCHAR get_pos_data(); 
UCHAR nget_pos_data(); 


// common entry point for calls to Strategy routines 


int main(PREQPACKET rp ) 
{ 
Volo. *ptr; 
ant “ppt ry 
PLINFOSEG liptr; // pointer to local info seg 
anit 3 
ULONG addr; 
USHORT in_data; 


switch (rp->RPcommand) 

2: RPINIT: // 0x00 
// init called by kernel in protected mode ring 3 with IOPL 
return Init (rp); 

case RPOPEN: // 0x0d 


// get current processes id 


if (GetDOSVar (2, &ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


// get process info 

liptr = *((PLINFOSEG *) ptr); 

// if this device never opened, can be opened by any process 
if (opencount == 0) // first time this device opened 

: opencount=1; // set open counter 


savepid = liptr->pidCurrent; // save current process id 


i 


else 
{ 
if (savepid != liptr->pidCurrent) // another proc tried to open 
return (RPDONE | RPERR | RPBUSY ); // so return error 
++opencount; // bump counter, same pid 


} 
return (RPDONE) ; 


case RPCLOSE: // O0x0e 
// get process info of caller 


if (GetDOSVar(2,é&ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND); // no info 


// get process info from os/2 


liptr= *((PLINFOSEG *) ptr); // ptr to process info seg 


// 
Leif: 
// 
// 
// 


it 


// 


make sure that process attempting to close this device 
one that originally opened it and the device was open in 


first place. 


(savepid != liptr->pidCurrent || opencount == 0) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


if an LDT selector was allocated, free it 


PhysToUVirt (board_address,0x8000,2, 
(FARPOINTER) &addr_struct.mapped_addr) ; 


--opencount; 
return (RPDONE); 


case RPREAD: 


return (RPDONE) ; 


case RPWRITE: 








return (RPDONE) ; 


case RPIOCTL: 


// close counts down open counter 
// veturn 'done' status to caller 


// 0x04 


// 0x08 


// 0x10 


OUR_CAT) // only our category 


if (rp->s.I0Ctl.category != 
return (RPDONE) ; 
switch (rp->s.IOCtl.function) 


{ 


// this IOCtl returns the bus type. 


// the return is Oxff01. If ISA, the return is ff00 


case 0x01: 
return (RPDONE | RPERR | bus); 


// this IOCtl maps an adapter memory to an LDT selector:offset, 
// and sends it to the application for direct application reads 


// and writes 


case 0x02: 


// check if MCA or ISA 


// send memory-mapped addr to app 


// verify caller owns this buffer area 


if (VerifyAccess ( 


SELECTOROF (rp->s.I0Ctl.buffer), // selector 
OFFSETOF (rp->s.10Ctl.buffer), // offset 


8, 
1) ) 


// 8 bytes 
// vead write 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// lock the segment down temp 


if (LockSeg ( 


SELECTOROF (rp->s.IOCtl.buffer), // selector 


0, // lock < 2 sec 
0, // wait for seg lock 
(PLHANDLE) &lock_seg_han) ) // handle returned 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


If the type is Micro Channel 


// map the board address to an LDT entry 
if ( PhysToUVirt (board_address,0x8000,1, 
(FARPOINTER) &addr_struct .mapped_addr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// move data to users buffer 


if (MoveBytes ( 


é&addr_struct, // source 
rp->s.10Ctl.buffer, // dest 
8) ) // 8 bytes 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// unlock segment 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


return (RPDONE); 


// this IOCtl demonstrates how an application program can get the 
// contents of a Micro Channel Adapter's POS registers 


case 0x03: // get pos reg data 
// verify caller owns this buffer area 


if (VerifyAccess ( 

SELECTOROF (rp->s.IO0Ctl.buffer), // selector 

OFFSETOF (rp->s.I0Ctl.buffer), // offset 

6, // 6 bytes 

1) ) // read write 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// lock the segment down temp 


if (LockSeg ( 

SELECTOROF (rp->s.IO0Ctl.buffer), // selector 

0, // lock < 2 sec 

0; // wait for seg lock 
(PLHANDLE) &lock_seg_han) ) // handle returned 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// move slot data to driver buffer 


if (MoveBytes ( 


(FARPOINTER) appl_buffer, // source 
é&pos_struct, // for pos data 
6)) // 6 bytes 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
pos_struct.data = get_pos_data(pos_struct.slot,pos_struct.reg) ; 
// move POS reg data to users buffer 


if (MoveBytes ( 


&pos_struct, // for pos data 
(FARPOINTER) appl_buffer, // source 
6)) // 6 bytes 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// unlock segment 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
return (RPDONE); 


// this IOCtl is essentially the same as 0x02, except the 

// user virtual address is mapped to a li address in the 

// process address range and then sent to the application. This 
// save the SelToFlat and FlatToSel each time the pointer is 

// vceferenced. 


case 0x04: // 32-bit memory-mapped addr to app 
// verify caller owns this buffer area 


if (VerifyAccess ( 

SELECTOROF (rp->s.IO0Ctl.buffer), // selector 

OFFSETOF (rp->s.10Ctl.buffer), // offset 

8, // 8 bytes 

a): 4) // read write 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// lock the segment down temp 


if (LockSeg ( 

SELECTOROF (rp->s.IOCtl.buffer), // selector 

0. // lock < 2 sec 

0, // wait for seg lock 
(PLHANDLE) &lock_seg_han) ) // handle returned 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// map the board address to an LDT entry 
if ( PhysToUVirt (board_address,0x8000,1, 
(FARPOINTER) &addr_struct.mapped_addr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// now convert it to a li address 


if (VirtToLin((FARPOINTER) addr_struct.mapped_addr, 


(PLINADDR) &addr_struct .mapped_addr) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


// move data to users buffer 


if (MoveBytes ( 


é&addr_struct, // source 
rp->s.10Ctl.buffer, // dest 
8) ) // 8 bytes 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
// unlock segment 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


return (RPDONE) ; 


} // switch (rp->s.IOCtl.function 


case RPDEINSTALL: // 0x14 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
// all other commands are ignored 


default: 
return (RPDONE) ; 


int hex2bin(char c) 


{ 
if(c < 0x3a) 


return (c —- 48); 
else 
return (( c & Oxdf) - 55); 


USHORT get_POS(USHORT slot_num,USHORT *card_ID,UCHAR *pos_regs) 


{ 
USHORT rc, i, lid; 


if (GetLIDEntry(0x10, 0, 1, &lid)) // get LID for POS 
return (1); 


// Get the size of the LID request block 


ABIOS_1_blk.f_parms.req_blk_len = sizeof(struct lid_block_def) ; 
ABIOS_1_blk.f_parms.LID = lid; 

ABIOS_1_blk.f_parms.unit = 0;; 

ABIOS_1_blk.f_parms.function = GET_LID_BLOCK_SIZE; 
ABIOS_1_blk.f_parms.ret_code = 0x5a5a; 
ABIOS_1_blk.f_parms.time_out = 0; 


if (ABIOSCall(lid,0, (void *) &ABIOS_1_blk) ) 
return (1); 


lid_blk_size = ABIOS_1_blk.s_parms.blk_size; // Get the block size 


// Fill POS regs and card ID with FF in case this does not work 


*card_ID = OxFFFF; 
for (i=0; i<NUM_POS_BYTES; i++) { pos_regs[i] = 0x00; }; 


// Get the POS registers and card ID for the commanded slot 








ABIOS_r_blk.f_parms.req_blk_len = lid_blk_size; 
ABIOS_r_blk.f_parms.LID = lid; 
ABIOS_r_blk.f_parms.unit = 0;; 
ABIOS_r_blk.f_parms.function = READ_POS_REGS_CARD; 
ABIOS_r_blk.f_parms.ret_code = 0x5a5a; 
ABIOS_r_blk.f_parms.time_out = 0; 
ABIOS_r_blk.s_parms.slot_num = (UCHAR)slot_num & Ox0OF; 
ABIOS_r_blk.s_parms.pos_buf = (void *)pos_regs; 
ABIOS_r_blk.s_parms.card_ID = OxFFFF; 

if (ABIOSCall(lid,0, (void *)&ABIOS_r_blk) ) 

re = 1; 
else { // Else 





*card_ID = ABIOS_r_blk.s_parms.card_ID; // Set the card ID 


value 


FreeLIDEntry (lid); 
return (rc); 


UCHAR get_pos_data (int slot, int reg) 
{ 

UCHAR pos; 

CARD *cptr; 


cptr = &card[slot-1]; // set pointer to beg of card array 
if (reg == 0) // card ID 
pos = LOUSHORT (cptr->card_ID); 
else 
if ( reg == 1) 
pos = HIUSHORT (cptr->card_ID); 
else 


pos = cptr->pos_regs[reg-2]; // POS data register 
return (pos); 
} 
// Device Initialization Routine 
int Init (PREQPACKET rp) 
{ 
USHORT lid; 
register char *p; 
// store DevHlp entry point 


DevHlp = rp->s.Init.DevHlp; // save DevHlp entry point 


if (!(GetLIDEntry (0x10, 0, 1, &lid))) { // get LID for POS 
FreeLIDEntry (lid); 


// Micro Channel (tm) setup section 
bus = 1; // MCA bus 
// Get the POS data and card ID for each of 8 possible slots 


for (i=0;i <= MAX_NUM_SLOTS; i++) 
get_POS (i+1, (FARPOINTER) &card[i].card_ID, (FARPOINTER) card[i].pos_regs) ; 


matches = 0; 
for (i=0, pcard = card; i <= MAX_NUM_SLOTS; i++, pcardt++) { 
if (pcard->card_ID == TARGET_ID) { 
matches = 1; 
break; 
} 
} 
if (matches == 0) { // at least one board found 


DosPutMessage(1, 8, devhdr.DHname) ; 

DosPutMessage(1,strlen(NoMatchMsg) ,NoMatchMsg) ; 
rp->s.InitExit.finalCS = (OFF) 0; 

rp->s.InitExit.finalDS = (OFF) 0; 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

} 


// calculate the board address from the POS regs 
board_address = ((unsigned long) get_pos_data(i+l, 4) << 16) | 
((unsigned long) (get_pos_data(i+l, 3) & 1) << 15); 

} 
else 


// ISA bus setup 


{ 
bus = 0; // ISA bus 


// get parameters, IRQ (not used yet), port addr and base mem addr 


for (p = rp->s.Init.args; *p && *p != ' ';++p);// skip driver name 
for (; *p == ' '; ++p); // skip blanks following driver name 
if (*p) 
{ 
board_address=0; // i/o port address 
for (; *p != '\0'; ++p) // get board address 
board_address = (board_address << 4) + (hex2bin(*p)); 


addr_struct.board_addr = board_address; 
} 
} 


if (bus) 
DosPutMessage(1,strlen(MainMsgMCA) ,MainMsgMCA) ; 

else 
DosPutMessage(1,strlen(MainMsgISA) ,MainMsgISA) ; 


// send back our cs and ds end values to os/2 


if (SegLimit (HIUSHORT((void *) Init), &rp->s.InitExit.finalcs) || 
SegLimit (HIUSHORT((void *) MainMsgISA), &rp->s.InitExit.finalDS) ) 
Abort (); 


’ 


Beep (200, 500) 

Beep (200,500); 

Beep (250,500); 
) 
) 
) 


7 


Beep (300,500 
Beep (250, 500 
Beep (300, 500 


’ 


’ 


return (RPDONE) ; 


Figure A-7. Memory-mapped driver, 32-bit version. 


/* file sample.c 
sample OS/2 serial device driver 


*Y, 


#include "drvlib-.h" 
#include "uart.h" 
#include "serial.h" 


extern void near STRAT(); /* name of strat rout.*/ 
extern void near TIM_HNDLR(); /* timer handler */ 


extern int near INT_HNDLR(); /* interrupt hand */ 


DEVICEHDR devhdr = { 














(void far *) OXFFFFFFFF, /* link */ 

(DAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute */ 

(OFF) STRAT, /* &strategy a7. 

(OFF) 0, /* &IDCroutine ee 

"DEVICE1 " 

di 
CHARQUEUE rx_queue; /* receiver queue */: 
CHARQUEUE tx_queue; /* transmitter queue */ 
FPFUNCTION DevHlp=0; /* for DevHlp calls */ 
LHANDLE lock_seg_han; /* handle for locking*/ 
PHYSADDR appl_buffer=0; /* address of caller */ 
PREQPACKET p=OL; /* Request Packet ptr*/ 
ERRCODE err=0; /* error return */: 
void far *ptr; /* temp far pointer */ 
DEVICEHDR *HpLYy /* pointer to Device */ 
USHORT 1; /* general counter aes 
UARTREGS uart_regs; /* uart registers aed 
ULONG WriteID=0L; /* ID for write Block*/ 
ULONG ReadID=0L; /* ID for read Block */ 
PREQPACKET ThisReadRP=0L; /* for read Request */ 
PREQPACKET ThisWriteRP=0L;/* for write Request */ 
char inchar, outchar;/* temp chars */ 
USHORT baud_rate; /* current baud rate */ 
unsigned int savepid; /* PID of driver own */ 
UCHAR opencount; /* number of times *7 
ULONG tickcount; /* for timeouts ed 
unsigned int com_error_word; /* UART status */ 
USHORT port; /* port variable ond 
USHORT temp_bank; /* holds UART bank */ 
QUEUE rqueue; /* receive queue info*/ 


void near init(); 

void near enable_write(); 
void near disable_write(); 
void near set_dlab(); 

void near reset_dlab(); 
void near config_82050(); 


char IntFailMsg[] = " interrupt handler failed to install.\r\n"; 
char MainMsg[] = " OS/2 Serial Device Driver V1.0 installed.\r\n"; 


/* common entry point to strat routines */ 


int main(PREQPACKET rp, int dev ) 
{ 
void far *ptr; 
int far *pptr; 
PLINFOSEG liptr; /* pointer to local info */ 
int <i; 
ULONG addr; 
switch (rp->RPcommand) 
{ 
case RPINIT: /* 0x00 */ 


/* init called by kernel in prot mode */ 


return Init (rp,dev) ; 


case RPOPEN: /* Ox0d */ 
/* get current processes id */ 


if (GetDOSVar (2, &ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


/* get process info */ 
liptr = *((PLINFOSEG far *) ptr); 
/* if this device never opened */ 


if (opencount == 0) /* 1st time dev op'd*/ 
{ 
ThisReadRP=0L; 
ThisWriteRP=0L; 
opencount=1; /* set open counter ef 
savepid = liptr->pidCurrent; /* PID */ 
QueuelInit (&rx_queue);/* init driver */ 
Queuelnit (&tx_queue) ; 


} 


else 
{ 
if (savepid != liptr->pidCurrent) 
return (RPDONE | RPERR | RPBUSY ); 
++topencount; /* bump counter */ 


} 
return (RPDONE) ; 


case RPCLOSE: /* Ox0e */ 
/* get process info of caller */ 


if (GetDOSVar (2, é&ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; /* no info */ 


/* get process info from os/2 */ 


liptr= *((PLINFOSEG far *) ptr); /* PID */ 

if (savepid != liptr->pidcurrent | | 
opencount == 0) 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

--opencount; /* close counts down open*/ 


if (ThisReadRP !=0 && opencount == 0) { 
Run((ULONG) ThisReadRP); /* dangling*/ 
ThisReadRP=0L; 

} 

return (RPDONE); /* return 'done' ee 





case RPREAD: /* 0x04 */ 
/* Try to read a character */ 


ThisReadRP = rp; 
if (opencount == 0)/* drvr was closed ay: 
{ 
rp->s.ReadWrite.count = 0; /* EOF */ 
return (RPDONE) ; 
} 
com_error_word=0;/* start off no errors */ 
ReadID = (ULONG) rp; 


if (Block(ReadID, -1L, 0, &err)) 
if (err == 2) /* interrupted */ 
return (RPDONE | RPERR|ERROR_CHAR_CALL_INTERRUPTED) ; 


if (rx_queue.qcount == 0) { 
rp->s.ReadWrite.count=0; 
return (RPDONE|RPERR|ERROR_NOT_READY) ; 


} 


i=0; 
do { 
if (MoveData((FARPOINTER) &inchar, 
(FARPOINTER) (rp->s.ReadWrite.bufferti), 
1, 
MOVE_VIRTTOPHYS) ) 
return (RPDONE |RPERR|ERROR_GEN_FAILURE) ; 
} 
while (++i < rp->s.ReadWrite.count 
&& !QueueRead (&rx_queue, &inchar) ); 
rp->s.ReadWrite.count = i; 
Queuelnit (&rx_queue) ; 
return (rp->RPstatus) ; 


case RPWRITE: /* 0x08 #7 
ThisWriteRP = rp; 
/* transfer characters from user buffer */ 


addr=rp->s.ReadWrite.buffer;/* get addr */ 
for (i = rp->s.ReadWrite.count; i; --i,++addr) 
{ 
if (MoveData((FARPOINTER) addr, 
(FARPOINTER) &é0utchar, 
1, 
MOVE_PHYSTOVIRT) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (QueueWrite (&tx_queue, outchar) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


} 
WriteID = (ULONG) rp; 
enable_write(); 


if (Block(WriteID, -1L, 0, éerr)) 


if (err == 2) /* interrupted xf 
return (RPDONE|RPERR|ERROR_CHAR_CALL_INTERRUPTED) ; 


tickcount=MIN_TIMEOUT; /* reset timeout */ 
QueuelInit (&tx_queue) ; 
return (rp->RPstatus) ; 


case RPINPUT_FLUSH: /* 0x07 ats 


QueueF lush (&rx_queue) ; 
return (RPDONE) ; 


case RPOUTPUT_FLUSH: /* Ox0b */ 


QueueF lush (&tx_queue) ; 
return (RPDONE) ; 





case RPIOCTL: /* 0x10 Lay 


!((rp->s.1I0Ctl.category == SAMPLE_CAT) 
| (rp->s.I0Ctl.category == 0x01))) 
return (RPDONE); 


ie 
| 


switch (rp->s.IOCtl.function) 
{ 


case 0x41: /* set baud rate */ 
/* set baud rate to 1.2, 2.4, 9.6, 19.2 */ 
/* verify caller owns the buffer area */ 


if (VerifyAccess ( 
SELECTOROF (rp->s.IOCtl.parameters), 
OFFSETOF (rp->s.IOCtl.parameters), 
Dy /* two bytes at 
1) ) /* read/write */ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.IOCtl.parameters), 

0, /* lock for < 2 sec *p 
0, /* wait for seg lock */ 


(PLHANDLE) &lock_seg_han)) /* handle */ 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* get physical address of buffer */ 
if (VirtToPhys ( 
(FARPOINTER) rp->s.IOCtl.parameters, 
(FARPOINTER) &appl_buffer) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* move data to local driver buffer */ 


if (MoveData ( 


(FARPOINTER) appl_buffer, /* source #/ 
(FARPOINTER) &baud_rate, /* destination x, 
2, /* 2 bytes fF 


MOVE_PHYSTOVIRT) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (UnPhysToVirt()) /* release selector*/ 
return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 


/* unlock segment */ 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 





switch (baud_rate) 


{ 
case 1200: 


uart_regs.Bal=0xe0; 
uart_regs.Bah=0x01; 
break; 


case 2400: 
uart_regs.Bal=0xf0; 


uart_regs.Bah=0x00; 
break; 


error: 


case 9600: 


uart_regs.Bal=0x3c; 
uart_regs.Bah=0x00; 
break; 


case 19200: 
uart_regs.Bal=0xle; 
uart_regs.Bah=0x00; 
break; 

case 38400: 
uart_regs.Bal=0x0f; 


uart_regs.Bah=0x00; 
break; 


return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 
} 


init(); /* reconfigure uart at 
return (RPDONE); 


case 0x68: /* get number of chars */ 


/* verify caller owns the buffer */ 


if (VerifyAccess ( 

SELECTOROF (rp->s.10Ctl.buffer), 

OFFSETOF (rp->s.10Ctl.buffer), 

4, /* 4 bytes ¥/) 

Ly) 3 /* read/write */ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.10Ctl.buffer), 

0, /* lock for < 2 sec a 
0, /* wait for seg lock ea 


(PLHANDLE) &lock_seg_han)) /* handle*/ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* get physical address of buffer */ 


if (VirtToPhys ( 
(FARPOINTER) rp->s.IOCtl.buffer, 
(FARPOINTER) &appl_buffer) ) 

return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


rqueue.cch=rx_queue.qcount; 
rqueue.cb=rx_queue.qsize; 


/* move data to local driver buffer */ 


if (MoveData ( 

(FARPOINTER) &rx_queue, /* source alt 

(FARPOINTER) appl_buffer, /* dest */ 

4, /* 4 bytes */ 
MOVE_PHYSTOVIRT) ) 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (UnPhysToVirt () ) 
return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 
/* unlock segment */ 


han) ) 
R | ERROR_GEN_FAILURE) ; 


if (UnLockSeg (lock_seg_| 
return (RPDONE|RPER 





return (RPDONE) ; 

case Ox6d: /* get COM error info el: 
/* verify caller owns the buffer at A 
if (VerifyAccess ( 
SELECTOROF (rp->s.10Ctl.buffer), 
OFFSETOF (rp->s.10Ctl.buffer), 
25 /* two bytes x7. 
Te 3) /* read/write a 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
/* lock the segment down temp */ 


if (LockSeg ( 
SELECTOROF (rp->s.1I0Ctl.buffer), 


0, /* lock for < 2 sec */ 
0, /* wait for seg lock */ 
(PLHANDLE) &lock_seg_han)) /* handle*/ 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
/* get physical address of buffer */ 


LE (VPreTS 
(FARPOINTE 
(FARPOINTE 

return 


Phys ( 

R) rp->s.10Ctl.buffer, 

R) &appl_buffer) ) 

(RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* move data to application buffer */ 


if (MoveData ( 





(FARPOINTER) &com_error_word, /* source */ 
(FARPOINTER) appl_buffer, /* dest 4 
2, /* 2 bytes */ 


MOVE_VIRTTOPHYS) ) 


return (RPDONE|RPE 


if (UnPhysToVirt () ) 


return (RPDONE|RPER 
/* unlock segment */ 


if (UnLockSeg (lock_seg_| 
return (RPDONE|RPER 


RR | ERROR_GEN_FAILURE) ; 


R|ERROR_GEN_FAILURE) ; 


han) ) 
R |ERROR_GEN_FAILURE) ; 





return (RPDONE) ; 


default: 
return (RPDONE |RPERR|ERROR_GEN_FAILURE) ; 
} 


/* don't allow deinstall */ 


case RPDEINSTALL: /* 0x14 ep 
return (RPDONE | RPERR|ERROR_BAD_COMMAND) ; 


/* all other commands are ignored */ 


default: 
return (RPDONE) ; 


void enable_write() 
/* enable write interrupts on uart */ 


{ 
int port; 
int reg_val; 


port=UART_PORT_ADDRESS; 
reg_val=inp(port+2) & 0x60; 
set_bank (00); 
outp((portt1),inp(port+1) | 0x12); 
outp ((port+2),reg_val) ; 


} 


void disable_write() 
/* turn off write interrupts on uart */ 


{ 
int port; 
int reg_val; 
port=UART_PORT_ADDRESS; 
reg_val=inp(port+2) & 0x60; 
set_bank (00); 


outp((port+1),inp(portt+1l) & Oxed); 
outp((port+2),reg_val); 


} 
void init () 
/* intializes software and configures 82050 */ 
{ 
config_82050 (); /* Configure 82050 x7] 
set_bank (01); 
} 
void config_82050() 
/* Configure the 82050 x] 
int port; 
int inval; 


Disable(); /* disable interrupts 
port=UART_PORT_ADDRESS; 


x} 


} 


void set_dlab 


/* set stick bit */ 


set_bank (01); 
outp ((port+7) ,0x10); 


outp ((portt+1l), uart_regs.Txf) ; 
set_bank (02); 

outp ((port + 4), uart_regs.Imd); 
outp ((port + 7), uart_regs.Rmd) ; 
outp ((port + 5), uart_regs.Acrl); 
outp ((port + 3), uart_regs.Tmd) ; 
outp ((port + 1), uart_regs.Fmd) ; 
outp ((port + 6), uart_regs.Rie); 
set_bank (03); 

outp ((port + 0), uart_regs.Clcf); 
set_dlab (03); 

outp ((port + 0), uart_regs.Bbl); 
outp ((port + 1), uart_regs.Bbh) ; 
reset_dlab (03); 

outp ((port + 3), uart_regs.Bbcf) ; 
outp ((port + 6), uart_regs.Tmie) ; 
set_bank (00); 

outp ((port + 1), uart_regs.Ger); 
outp ((port + 3), uart_regs.Lcr); 
outp ((port + 7), uart_regs.Acr0); 
outp ((port + 4), uart_regs.Mcr_0); 
set_dlab (00); 

outp ((port + 0), uart_regs.Bal); 
outp ((port + 1), uart_regs.Bah); 


reset_dlab (00); 
set_bank (01); 


Enable(); 


(bank) 


/* stick bit 
/* reset port 
/* stick bit 


/* general config 


/*auto rupt 


J* onti-z 
/* no 9 bit 
f* ex £103 
/* enable 


/* modemconfiguration 


/* clock 


/* 


BRGB lsb 
BRGB msb 


BRGB 
timer b 


general cfg 
enable 

8 bit 

CR 

no DTR 


BRGA lsb 
BRGA msb 


turn on 


Set DLAB bit to allow access to divisior registers 


/* 

int bank; 

{ 
int inval; 
int port; 
port=UART_PORT_ADDRESS; 
set_bank (00); 
inval=inp(port +3); 
inval =inval | 0x80; 
outp ((port+3),inval); 
set_bank (bank); 

} 

getsrc() 

{ 
int vV,SrC; 
int port; 


port=UART_PORT_ADDRESS; 
v=inp(port+2); 


/* set dlab in LCR 


/* get base address 


/* 


get data 


ef 


Ay 


AO. 


Ay: 


src=v & 0x0e; /* mask bits */ 
src=src/2; /* divide by 2 */ 
return(src); /* and pass it back */ 

set_bank (bank_num) 

/* set bank of 82050 uart */ 

int bank_num; 


int reg_val; 
int port; 


reg_val=bank_num*0x20; /* select bank numb */ 
port=UART_PORT_ADDRESS; /* get real port a 
outp (port+gir_addr, reg_val); /* output */. 


void reset_dlab (bank) 
/* Reset DLAB bit of LCR a 


int bank; 


int inval; 
int port; 


port=UART_PORT_ADDRESS; 
set_bank (00); 
inval=inp (port +3); 
inval = (inval & Ox7f); /* dlab = 0 in LCR */ 
outp ((port+3),inval); 
set_bank (bank); 
} 


/* 82050 interrupt handler */ 


void interrupt_handler () 
{ 

int rupt_dev; 

int source; 

int cmd_b; 

int st_b; 

int port; 

int temp; 

int rxlevel; 


port=UART_PORT_ADDRESS; 

outp ((port+2) ,0x20); /* switch to bank 1 */ 
source = getsrce (); /* get vector *y 
switch (source) 


{ 
/* optional timer service routine */ 
case timer 


st_b=inp (port+3); /* dec transmit count */ 
if ( ThisReadRP == 0) /* nobody waiting arg 


break; 
ThisReadRP->RPstatus=(RPDONE|RPERR|ERROR_NOT_READY) ; 
Run ((ULONG) ThisWriteRP) ; /* run thread 
ThisWriteRP=0; 
break; 


case txm 
case txf 


/* spurious write interrupt */ 


if ( ThisWriteRP == 0) { 
temp=inp (port+2) ; 
break; 


/* keep transmitting until no data left */ 

if (! (QueueRead (&tx_queue, &£outchar) ) ) 
outp((port), outchar); 
tickcount=MIN_TIMEOUT; 


break; 


} 

/* done writing, run blocked thread at 

tickcount=MIN_TIMEOUT; 

disable_write(); 

ThisWriteRP->RPstatus = (RPDONE); 

Run ((ULONG) ThisWriteRP) ; 

ThisWriteRP=0; 

break; 

case ccr 
/* control character, treat as normal ef 
inchar=inp(portt5) ; 
case rxf 

/* vx fifo service routine */ 

if ( ThisReadRP == 0) 
inchar=inp (port); /* get character */ 

else 

{ 

temp=inp (port+4) ; 

rxlevel=(temp & 0x70) / 0x10; 

/* empty out chip FIFO */ 

while (rxlevel !=0) { 
inchar=inp (port); /* get character */ 
rxlevel--; 
tickcount=MIN_TIMEOUT; 


/* write input data to queue */ 


if (QueueWrite (&rx_queue, inchar) ) 


/* error, queue must be full */ 


{ 
ThisReadRP->RPstatus=(RPDONE|RPERR|ERROR_GEN_FAILURE) ; 


Run ((ULONG) ThisReadRP) ; 
ThisReadRP=0; 

break; 

} 


com_error_word |= inp(port+5); 


} /* while rxlevel */ 
} /* else */ 
} /* switch (source) */ 
EOI (5); 
} 
void timer_handler () 


{ 
if (ThisReadRP == 0) 
return; 


tickcount--; 

if(tickcount == 0) { 
ThisReadRP->RPstatus=(RPDONE) ; 
Run ((ULONG) ThisReadRP) ; 
ThisReadRP=0L; 
tickcount=MIN_TIMEOUT; 
} 

} 


/* Device Initialization Routine */ 
int Init (PREQPACKET rp, int dev) 
{ 
register char far *p; 
/* store DevHlp entry point */ 
DevHlp = rp->s.Init.DevHlp; 


/* install interrupt hook in vector */ 


if (SetTimer ((PFUNCTION) TIM_HNDLR) ) 
goto fail; 


rx_queue.qsize=QUEUE_SIZE; 


tx_queue.qsize=QUEUE_SIZE; /* init queue xf 
init(); /* init the port */ 
tickcount=MIN_TIMEOUT; /* set timeout oy 


if (SetIRQ(5, (PFUNCTION) INT_HNDLR,0)) { 


/* if we failed, deinstall driver cs+ds=0 */ 
fail: 

DosPutMessage(1, 8, devhdr.DHname) ; 

DosPutMessage (1,strlen(IntFailMsg) ,IntFailMsg) ; 

rp->s.InitExit.finalCS = (OFF) 0; 

rp->s.InitExit.finalDS = (OFF) 0; 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

} 


/* output initialization message */ 


DosPutMessage(1, 8, devhdr.DHname) ; 


DosPutMessage(1, strlen(MainMsg), MainMsg) ; 
/* send back our cs and ds values to os/2 */ 


if (SegLimit (HIUSHORT((void far *) Init),&érp->s.InitExit.finalCs) 
| | SegLimit (HIUSHORT((void far *) MainMsg), 
&rp->s.InitExit.finalDS) ) 
Abort (); 
return (RPDONE) ; 


Figure A-8. Serial device driver, 16-bit version. 


/* file sample.c 
sample OS/2 serial device driver 
Baye 
#include "drvlib-.h" 
#include "uart.h" 
#include "serial.h" 
#include <stdio.h> 


int main (PREQPACKET rp, int d); 


DEVICEHDR devhdr = { 











(void *) OXFFFFFFFF, /* link */ 
(DAW_CHR | DAW_OPN | DAW_LEVEL1),/* attribute ui, 
&main, /* &strategy */ 
0, /* &IDCroutine */ 
"DEVICE1 " 
di 
CHARQUEUE rx_queue; /* receiver queue xf 
CHARQUEUE tx_queue; /* transmitter queue */ 
PFUNCTION DevHlp=0; /* for DevHlp calls */ 
LHANDLE lock_seg_han; /* handle for locking*/ 
PHYSADDR appl_buffer=0; /* address of caller */ 
PREQPACKET p=OL; /* Request Packet ptr*/ 
ERRCODE err=0; /* error return Ae. 
void ptr; /* temp pointer */ 
DEVICEHDR *hptr; /* pointer to Device */ 
USHORT 1; /* general counter #7 
UARTREGS uart_regs; /* uart registers xf; 
ULONG WriteID=0L; /* ID for write Block*/ 
ULONG ReadID=0L; /* ID for read Block */ 
PREQPACKET ThisReadRP=0L; /* for read Request */ 
PREQPACKET ThisWriteRP=0L;/* for write Request */ 
char inchar, outchar;/* temp chars «7 
USHORT baud_rate; /* current baud rate */ 
unsigned int savepid; /* PID of driver own */ 
UCHAR opencount; /* number of times oe 
ULONG tickcount; /* for timeouts */ 
unsigned int com_error_word; /* UART status */ 
USHORT port; /* port variable * 
USHORT temp_bank; /* holds UART bank ea 
QUEUE rqueue; /* receive queue info*/ 


void 
void 
void 
void 
void 
void 


char 
char 


/* 3G 


init(); 
enable_write(); 
disable_write(); 
set_dlab(); 


reset_dlab(); 
config_82050(); 

IntFailMsg[] = " interrupt handler failed to install.\r\n"; 
MainMsg[] = " OS/2 Serial Device Driver V1.0 installed.\r\n"; 


ommon entry point to strat routines */ 


int main(PREQPACKET rp, int dev ) 


{ 


v 
a. 
P 
a 
U 


Ss 


old, “ptr; 

ne *pptr; 

LINFOSEG liptr; /* pointer to local info */ 
nt i; 

LONG addr; 


witch (rp->RPcommand) 


{ 
case RPINIT: /* 0x00 */ 


/* init called by kernel in prot mode */ 
return Init (rp, dev); 

case RPOPEN: /* Ox0d */ 
/* get current processes id */ 


if (GetDOSVar(2,é&ptr) ) 
return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


/* get process info */ 
liptr = *((PLINFOSEG *) ptr); 
/* if this device never opened */ 


if (opencount == 0) /* 1st time dev op'd*/ 
{ 
ThisReadRP=0L; 
ThisWriteRP=0L; 
opencount=1; /* set open counter J 
savepid = liptr->pidCurrent; /* PID */ 
QueuelInit (&rx_queue);/* init driver */ 
QueuelInit (&tx_queue) ; 


} 


else 
{ 
if (savepid != liptr->pidCurrent) 
return (RPDONE | RPERR | RPBUSY ); 
++opencount; /* bump counter */ 


} 
return (RPDONE) ; 


case RPCLOSE: /* 0x0e so fe 
/* get process info of caller */ 


if (GetDOSVar (2, &ptr) ) 


return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; /* no info */ 
/* get process info from os/2 */ 


liptr= *((PLINFOSEG *) ptr); /* PID */ 

if (savepid != liptr->pidcurrent | | 
opencount == 0) 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

-—-opencount; /* close counts down open*/ 


if (ThisReadRP !=0 && opencount == 0) { 
Run((ULONG) ThisReadRP); /* dangling*/ 
ThisReadRP=0L; 


} 
return (RPDONE) ; /* return ‘done! #7; 


case RPREAD: /* 0x04 */ 
/* Try to read a character */ 


ThisReadRP = rp; 
if (opencount == 0)/* drvr was closed */ 
{ 
rp->s.ReadWrite.count = 0; /* EOF */ 
return (RPDONE) ; 
} 


com_error_word=0;/* start off no errors */ 


ReadID = (ULONG) rp; 
if (Block(ReadID, -1L, 0, é&err)) 
if (err == 2) /* interrupted */ 


return (RPDONE | RPERR|ERROR_CHAR_CALL_INTERRUPTED) ; 


if (rx_queue.qcount == 0) { 
rp->s.ReadWrite.count=0; 
return (RPDONE|RPERR|ERROR_NOT_READY) ; 
} 


i=0; 
do { 
if (MoveData((PVOID) &inchar, 
(PVOID) (rp->s.ReadWrite.bufferti), 
1, 
MOVE_VIRTTOPHYS) ) 
return (RPDONE |RPERR|ERROR_GEN_FAILURE) ; 
} 
while (++i < rp->s.ReadWrite.count 
&& !QueueRead (&rx_queue, &inchar) ); 
rp->s.ReadWrite.count = i; 
QueuelInit (&rx_queue) ; 
return (rp->RPstatus) ; 


case RPWRITE: 7*: 0x08 ef 
ThisWriteRP = rp; 
/* transfer characters from user buffer */ 


addr=rp->s.ReadWrite.buffer;/* get addr */ 
for (i = rp->s.ReadWrite.count; i; --i,++addr) 
{ 
if (MoveData((PVOID) addr, 
(PVOID) &outchar, 
1, 


MOVE_PHYSTOVIRT) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (QueueWrite (&tx_queue, outchar) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 
} 
WriteID = (ULONG) rp; 
enable_write(); 


if (Block(WriteID, -1L, 0, &err)) 
if (err == 2) /* interrupted ei: 
return (RPDONE|RPERR|ERROR_CHAR_CALL_INTERRUPTED) ; 


tickcount=MIN_TIMEOUT; /* reset timeout */ 
QueuelInit (&tx_queue) ; 
return (rp->RPstatus) ; 


case RPINPUT_FLUSH: /* 0x07 */ 


QueueF lush (&rx_queue) ; 
return (RPDONE) ; 


case RPOUTPUT_FLUSH: /* Ox0b */ 


QueueF lush (&tx_queue) ; 
return (RPDONE) ; 





case RPIOCTL: /* 0x10 x] 
if (!((rp->s.IOCtl.category == SAMPLE_CAT) 
|| (ep->s.Ioctl.category == 0x01))) 


return (RPDONE) ; 


switch (rp->s.IOCtl.function) 
{ 


case 0x41: /* set baud rate */ 
/* set baud rate to 1.2, 2.4, 9.6, 19.2 */ 
/* verify caller owns the buffer area */ 


if (VerifyAccess ( 

SELECTOROF (rp->s.IOCtl.parameters), 

OFFSETOF (rp->s.IOCtl.parameters), 

2. /* two bytes */ 

1) ) /* xvead/write */ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.IOCtl.parameters), 

0, /* lock for < 2 sec Ki 
0 /* wait for seg lock */ 


, 
(PLHANDLE) &lock_seg_han)) /* handle */ 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* get physical address of buffer */ 
if (VirtToPhys ( 
(PVOID) rp->s.IOCtl.parameters, 
(PVOID) é&appl_buffer) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* move data to local driver buffer */ 


error: 


if (MoveData ( 


(PVOID) appl_buffer, /* source ¥/ 
(PVOID) &baud_rate, /* destination tf 
2, /* 2 bytes 
MOVE_PHYSTOVIRT) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 
if (UnPhysToVirt()) /* release selector*/ 


return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 


/* unlock segment */ 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 





switch (baud_rate) 


{ 
case 1200: 


uart_regs 
uart_regs 
break; 


case 2400: 
uart_regs 
uart_regs 
break; 

case 9600: 
uart_regs 
uart_regs 
break; 

case 19200: 
uart_regs 
uart_regs 
break; 

case 38400: 
uart_regs 


uart_regs 
break; 


-Bal=0xe0; 
-Bah=0x01; 


-Bal=0xf0; 
- Bah=0x00; 


-Bal=0x3c; 
- Bah=0x00; 


-Bal=0xle; 
- Bah=0x00; 


-Bal=0x0f; 
- Bah=0x00; 


return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 


} 


init(); 


/* reconfigure uart ee) 


return (RPDONE) ; 


case 0x68: 


/* get number of chars */ 


/* verify caller owns the buffer ey: 


if (VerifyAccess ( 
SELECTOROF (rp->s.1I0Ctl.buffer), 
OFFSETOF (rp->s.10Ctl.buffer), 


4, 
1) ) 


/* 4 bytes */ 
/* read/write yk 


ies 


return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.10Ctl.buffer), 

0, /* lock for < 2 sec a /: 
0, /* wait for seg lock */ 


(PLHANDLE) &lock_seg_han)) /* handle*/ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* get physical address of buffer */ 
if (VirtToPhys ( 
(PVOID) rp->s.10Ctl.buffer, 
(PVOID) &appl_buffer) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


rqueue.cch=rx_queue.qcount; 
rqueue.cb=rx_queue.qsize; 


/* move data to local driver buffer */ 


if (MoveData ( 


(PVOID) &érx_queue, /* source xf 
(PVOID) appl_buffer, /* dest a 
4, /* 4 bytes oe a 


MOVE_PHYSTOVIRT) ) 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


if (UnPhysToVirt () ) 
return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 


/* unlock segment */ 


if (UnLockSeg (lock_seg_han) ) 
return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 





return (RPDONE) ; 
case O0x6d: /* get COM error info 7 
/* verify caller owns the buffer ih 


if (VerifyAccess ( 

SELECTOROF (rp->s.10Ctl.buffer), 

OFFSETOF (rp->s.10Ctl.buffer), 

25 /* two bytes ¥y/) 

1) ) /* read/write */ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* lock the segment down temp */ 


if (LockSeg ( 

SELECTOROF (rp->s.10Ctl.buffer), 

Oss /* lock for < 2 sec */ 
0, /* wait for seg lock ed 


(PLHANDLE) &lock_seg_han)) /* handle*/ 
return (RPDONE | RPERR | ERROR_GEN_FAILURE) ; 


/* get physical address of buffer */ 


if (VirtToPhys ( 


(PVOID) rp->s.IOCtl.bu 
(PVOID) &appl_buffer) ) 


ffer, 


return (RPDONE | RPERR|ERROR_GEN_FAILURE) ; 


/* move data to application buffer */ 


if (MoveData ( 
(PVOID) &com_error_word 
(PVOID) appl_buffer, 


, /* source */ 
/* dest xf 


25 /* 2 bytes */ 
MOVE_VIRTTOPHYS) ) 


return (RPDONE|RPE 


if (UnPhysToVirt () ) 
return (RPDONE|RPER 


/* unlock segment */ 


if (UnLockSeg (lock_seg_| 
return (RPDONE|RPER 


RR | ERROR_GEN_FAILURE) ; 


R |ERROR_GEN_FAILURE) ; 


han) ) 
R|ERROR_GEN_FAILURE) ; 





return (RPDONE) ; 


default: 
return (RPDONE|RPERR|ERROR_GEN_FAILURE) ; 
} 


/* don't allow deinstall */ 


case RPDEINSTALL: /* 0x14 ef 
return (RPDONE | RPERR|ERROR_BAD_COMMAND) ; 


/* all other commands are ignored */ 


default: 
return (RPDONE) ; 


} 
void enable_write() 
/* enable write interrupts on uart */ 


{ 
int port; 
int reg_val; 


port=UART_PORT_ADDRESS; 
reg_val=inp(port+2) & 0x60; 
set_bank (00); 
outp((portt1),inp(port+1) | 0x12); 
outp ((port+2),reg_val); 


} 


void disable_write() 
/* turn off write interrupts on uart */ 


{ 
int port; 
int reg_val; 


} 


port=UART_PORT_ADDRESS; 
reg_val=inp(port+2) & 0x60; 


set_bank (00); 


outp((port+1l),inp(port+l) & 
outp((port+2),reg_val) ; 


void init () 


Oxed) ; 


/* intializes software and configures 82050 */ 


{ 


config_82050 (); /* Configure 82050 aed 
set_bank (01); 

} 

void config_82050() 

/* Configure the 82050 */ 


int port; 
int inval; 


Disable(); 


port=UART_PORT_ADDRESS; 


/* set stick bit */ 


set_bank (01); 


outp ((port+7),0x10); 
outp ((portt+l), uart_regs.Txf) ; 





set_bank (02); 
outp ((port + 
outp ((port 
outp ((port 
outp ((port 
outp ((port 
outp ((port 


t+ +t t+ 
NrFwWUIT Ss 


set_bank (03); 


outp ((port + 0), 
set_dlab (03); 

outp ((port + 0), 
outp ((port + 1), 
reset_dlab (03); 
outp ((port + 3), 
outp ((port + 6), 


set_bank (00); 
outp ((port + 1), 
outp ((port + 3), 
outp ((port + 7) 
outp ((port + 4) 
set_dlab (00); 
outp ((port + 0), 
outp ((port + 1), 
reset_dlab (00); 
set_bank (01); 


, 


, 


uart_regs. 
.Rmd) ; 
-Acrl); 
.Tmd) ; 
.Fmd) ; 
-Rie); 


uart_regs 
uart_regs 
uart_regs 
uart_regs 
uart_regs 


uart_regs 


uart_regs 
uart_regs 


uart_regs 
uart_regs 


uart_regs 
uart_regs 
uart_regs 
uart_regs 


uart_regs 
uart_regs 


Imd) ; 


<GIcG£):; 


~Bb1); 
»Bbh); 


-Bbcf); 
.Tmie); 


-Ger); 
her )cs 
-Acr0); 
-Mcr_0); 


-Bal); 
.-Bah); 


/* disable interrupts 


/* stick bit 
/* reset port 
/* stick bit 


/* general config 


/*auto rupt 


f* Catia 
/* no 9 bit 
J* te Tito 
/* enable 


/* modemconfiguration 


/* clock 


/* BRGB lsb 
/* BRGB msb 


/* BRGB 
/* timer b 


/* general cfg 


/* enable 
/* 8 bit 
/* CR 

/* no DTR 


/* BRGA lsb 
/* BRGA msb 


ay 


} 


Enable (); 


void set_dlab (bank) 


/* turn on 


Set DLAB bit to allow access to divisior registers */ 


/* 

int bank; 

{ 
int inval; 
int port; 
port=UART_PORT_ADDRESS; 
set_bank (00); 
inval=inp(port +3); 
inval =inval | 0x80; 
outp ((port+3),inval); 
set_bank (bank); 

} 

getsrc() 


{ 


int V,SIrC; 
int port; 


port=UART_PORT_ADDRESS; 
v=inp(port+2); 

src=v & 0x0e; 
src=src/2; 

return(src); 


set_bank (bank_num) 


/* set bank of 82050 uart */ 


int 


} 


bank_num; 


int reg_val; 
int port; 


reg_val=bank_num*0x20; 
port=UART_PORT_ADDRESS; 
outp (port+gir_addr, reg_val); 


void reset_dlab (bank) 


/* 


int 


Reset DLAB bit of LCR */ 


bank; 


int inval; 
int port; 


port=UART_PORT_ADDRESS; 
set_bank (00); 
inval=inp (port +3); 
inval = (inval & Ox7f); 
outp ((port+3),inval); 


/* set dlab in LCR 


/* get base address 
/* get data 

/* mask bits 

/* divide by 2 

/* and pass it back 


/* select bank numb */ 
/* get real port ef 
/* output ai 


/* dlab = 0 in LCR 


A. 


fata 


EA 
ay: 
af 
A: 
*/- 


*/ 


set_bank (bank); 
} 


/* 82050 interrupt handler */ 


void interrupt_handler () 
{ 

int rupt_dev; 

int source; 

int cmd_b; 

int st_b; 

int port; 

int temp; 

int rxlevel; 


port=UART_PORT_ADDRESS; 

outp ((port+2) , 0x20); /* switch to bank 1 */ 
source = getsrce (); /* get vector *7 
switch (source) 


{ 
/* optional timer service routine */ 


case timer 


st_b=inp (port+3); /* dec transmit count +7 

if ( ThisReadRP == 0) /* nobody waiting a? 2 
break; 

ThisReadRP->RPstatus=(RPDONE|RPERR|ERROR_NOT_READY) ; 

Run ((ULONG) ThisWriteRP) ; /* run thread */ 

ThisWriteRP=0; 

break; 


case txm 
case txf 


/* spurious write interrupt */ 


if ( ThisWriteRP == 0) { 
temp=inp (port+2) ; 
break; 


/* keep transmitting until no data left */ 
if (! (QueueRead (&tx_queue, &0utchar) ) ) 


outp((port), outchar); 
tickcount=MIN_TIMEOUT; 
break; 


} 
/* done writing, run blocked thread */ 


tickcount=MIN_TIMEOUT; 
disable_write(); 
ThisWriteRP->RPstatus = (RPDONE) ; 
Run ((ULONG) ThisWriteRP) ; 
ThisWriteRP=0; 

break; 


case ccr 


/* control character, treat as normal ef 
inchar=inp(portt5) ; 

case rxf 
/* vx fifo service routine */ 


if ( ThisReadRP == 0) 
inchar=inp (port); /* get character */ 
else 
{ 
temp=inp (port+4) ; 
rxlevel=(temp & 0x70) / 0x10; 


/* empty out chip FIFO */ 
while (rxlevel !=0) { 


inchar=inp (port); /* get character */ 
rxlevel--; 
tickcount=MIN_TIMEOUT; 


/* write input data to queue */ 
if (QueueWrite (&rx_queue, inchar) ) 
/* error, queue must be full */ 


{ 
ThisReadRP->RPstatus=(RPDONE|RPERR|ERROR_GEN_FAILURE) ; 


Run ((ULONG) ThisReadRP) ; 
ThisReadRP=0; 

break; 

} 


com_error_word |= inp(port+5); 


} /* while rxlevel */ 
} /* else */ 
} /* switch (source) */ 
EOI (5); 
} 
void timer_handler () 
{ 
if (ThisReadRP == 0) 
return; 


tickcount--; 

if(tickcount == 0) { 
ThisReadRP->RPstatus=(RPDONE) ; 
Run ((ULONG) ThisReadRP) ; 
ThisReadRP=0L; 
tickcount=MIN_TIMEOUT; 
} 

} 


/* Device Initialization Routine */ 
int Init (PREQPACKET rp, int dev) 


{ 


register char *p; 


/* store DevHlp entry point */ 
DevHlp = rp->s.Init.DevHlp; 
/* install interrupt hook in vector */ 


if (SetTimer ((PFUNCTION) timer_handler) ) 
goto fail; 


rx_queue.qsize=QUEUE_SIZE; 


tx_queue.qsize=QUEUE_SIZE; /* init queue ei: 
init(); /* init the port */ 
tickcount=MIN_TIMEOUT; /* set timeout */ 


if (SetIRQ(5, (PFUNCTION) interrupt_handler,0)) { 


/* if we failed, deinstall driver cs+ds=0 */ 
fail: 

DosPutMessage(1, 8, devhdr.DHname) ; 

DosPutMessage (1,strlen(IntFailMsg) ,IntFailMsg) ; 

rp->s.InitExit.finalCS = (OFFSET) 0; 

rp->s.InitExit.finalDS = (OFFSET) 0; 

return (RPDONE | RPERR | ERROR_BAD_COMMAND) ; 

} 


/* output initialization message */ 


DosPutMessage(1, 8, devhdr.DHname) ; 
DosPutMessage(1, strlen(MainMsg), MainMsg) ; 


/* send back our cs and ds values to os/2 */ 


if (SegLimit (HIUSHORT((void *) Init),&rp->s.InitExit.finalCs) 


|| SegLimit (HIUSHORT((void *) MainMsg), 
&rp->s.InitExit.finalDS) ) 
Abort (); 

return (RPDONE) ; 


Figure A-9. Serial device driver, 32-bit version. 


